Nginx Documentation #345

mayamcdougall · 2016-04-21T00:17:43Z

Rough draft is complete. Still needs further revision and editing, but I wanted to share what I've gotten done so far.

View-able at http://smcdougall.github.io/Pico/nginx/

Any input is appreciated. 😃

PhrozenByte · 2016-04-21T14:00:09Z

nginx.md

+    _title: Advanced Configuration Tips
+    modular-pico-config: Modular Pico Config
+nav-url: /docs/
+gh_release: v1.0.2


mayamcdougall · 2016-04-21T16:41:45Z

I wasn't sure about those. I had just based it on another page, so I left them in. Thanks.

PhrozenByte · 2016-04-23T16:10:48Z

nginx.md

+
+```
+location / {
+	try_files $uri $uri/ /?$uri&$args


Missing ';'

mayamcdougall · 2016-04-23T16:47:00Z

Thanks, those semi-colons are the bane of my existence. I leave them off at least once every time I edit a config file. >.<

Unfortunately, it won't work in the Pico location block. It needs to send the variable externally to PHP, and because of how the blocks are processed, it won't "remember" it from the Pico block when it gets to the php block.

It's a two-step process, first the url is rewritten to "/?some/page/url" using the Pico block, then it checks it again and matches it against the PHP block. It then sends the page to php-fpm for external processing, which is when it needs to know the variable.

PhrozenByte · 2016-04-23T17:40:56Z

Ah, ic, thanks for the explanation 😃

PhrozenByte · 2016-04-23T17:49:03Z

_docs/config.md

-        try_files $uri $uri/ /pico/?$1&$args;
-    }
+If you're using Nginx, you can use the following configuration to enable URL rewriting. Don't forget to adjust the path (`/pico`; line `1` and `4`) to match your installation directory. You can then enable URL rewriting by setting `$config['rewrite_url'] = true;` in your `config/config.php`.
+```


GitHub Pages (i.e. Kramdown) unfortunately doesn't support fenced code blocks correctly (three different Markdown parses are a pain...). See http://smcdougall.github.io/Pico/docs/#nginx-configuration. But indentation works fine 😃

mayamcdougall · 2016-04-23T18:24:16Z

Huh, wow, I did not notice that. Why does it work in nginx.md then? Wouldn't they be processed the same?

(I put it in a code block because the * in the example was messing up my syntax highlighting in Atom.)

mayamcdougall · 2016-04-23T18:31:40Z

Oops, that was supposed to reissue the same commit... guess I did it wrong. 😆

(Figured it out)

PhrozenByte · 2016-04-23T18:33:49Z

Ah, no, Kramdown does support fenced code blocks, but it requires you to add a empty line before and after the fenced code block.

mayamcdougall · 2016-04-23T18:39:53Z

Ah, okay. Should be fixed now.

PhrozenByte · 2016-04-29T14:31:07Z

nginx.md

+
+```
+location ~ ^/pico(.*) {
+	try_files $uri $uri/ /pico/?$1&$args;


/pico/index.php?$1&$args;, see above

mayamcdougall · 2016-04-29T14:34:04Z

Reading this, we can save a round trip by directly rewriting to /index.php?$uri&$args.

I don't know if it really saves a "round trip" or not. My assumption for how it works is that it would just "tack on" the name of the index file if unspecified.

Either way, I'll add index.php to match it up closer with .htaccess.

PhrozenByte · 2016-04-29T14:38:45Z

nginx.md

+
+### Modular Pico Config
+
+Let's say you're a real Pico enthusiast and have several Pico websites running on the same server.  You may get tired of writing all these rules into each and every server configuration.  An easier solution might be to place all the common components (index, access denials, php rules) into a separate file and include it using `include /absolute/path/to/file`.  You could also add the rewrite rule to this file, but a better option would be to include a second file, that way you can chose to include it *only* when Pico is located in your Document Root.


I think it's a good idea to let the components, i.e.

An easier solution might be to place all the common components (index, access denials, php rules) into a separate file

directly link to the appropriate sections above 😃

mayamcdougall · 2016-04-29T14:46:04Z

Considering you're from Germany.... it would probably be in poor taste to call you a "Documentation Nazi", huh? 😒

Seriously though, I appreciate all the help. 😉

mayamcdougall · 2016-04-29T14:47:41Z

I think it's a good idea to let the components directly link to the appropriate sections above 😃

👍

mayamcdougall · 2016-04-29T15:26:42Z

I've tested test try_files $uri =404; and it seems to work properly. Oddly enough, even with cgi.fix_pathinfo = 1, my server returned an "Access Denied" message from PHP (it was not a message from Nginx). There must be another security option somewhere else in Ubuntu's default config that I don't know about.

mayamcdougall · 2016-04-29T15:44:35Z

😒 I just realized I could have replied to each of your comments inside the line-note.

I don't know, I guess I just thought that button was for adding a new note. 😞

PhrozenByte · 2016-04-29T15:49:35Z

Okay, I've finished reading. Reading and fixing should never happen simultaneous 😉 ~~You can btw directly answer to my comments by clicking the Add a line note button, otherwise the comments get completely out of order and it's extremely hard to follow the discussion.~~ (#edit: I've just noticed that you've found it already 😄)

Anyway, I'll answer your comments here this time.

General notes:
I love it! ❤️ Sure, there are small issues, but none of them is even close to being "mission critical" 😃 As you've already noticed (:smile:) I'm a perfectionist (:wink:), so please don't be offended by so many comments - they are all just very minor issues I stumbled over. I could have fixed them after merge myself, but it's your document, so I thought it would be better to tell you where I see open issues instead.

After you've finished your work I'll read it again and merge it (that's not urgent! Do it whenever you've time for it). Again, I cannot emphasise enough that the document is great! 👍

Section "Getting Started", first paragraph: #345 (comment)

While the example... starting point, here we will provide a more in-depth look at Nginx configuration.

Yeah, I like that! 👍

Splitting the document into subsections: #345 (comment)

I used "Getting Started" as an introduction to the tutorial portion of the page.

True. "Nginx Configuration" sounds good. This is completely up to you, it just came to my mind immediately after reading this sentence.

How to name blocks: #345 (comment)
Then maybe simply just "Nginx's server configuration is broken into blocks." or something like that? I just stumbled over it while reading 😄

Nginx and HTTPS: #345 (comment) + #345 (comment)
Yeah, I'm using Let's Encrypt, too (and I love it). 353a17b is a absolute perfect solution! 👍

Directory listing (autoindex off; and Options -Indexes): #345 (comment)
Ah, I see. Yeah, then it's probably best to simply remove the half sentence in brackets as it doesn't apply to nginx anyway.

Denying access globally: #345 (comment)
I look forward to your solution for it 😃

Moving the "Deny access" section below "PHP Configuration": #345 (comment)
Ah, okay, thanks for clarifying this!

PHP with nginx vs. PHP with Apache: #345 (comment)
Yep, simply remove the comparison, it's just fine then 😃

OS-Dependant examples: #345 (comment)
Hmm... I don't have a real solution for this. But you had one 😉 353a17b is just fine!

try_files instead of the very complex location regex, fastcgi_split_path_info and if: #345 (comment) + #345 (comment)
Yes, I've tested it, works like a charm. 😃

PhrozenByte · 2016-04-29T16:32:13Z

nginx.md

@@ -0,0 +1,192 @@
+---


Can you please move the file to in-depth/nginx.md?

mayamcdougall · 2016-04-29T16:49:43Z

[That line you removed about answering me this one time]

My excuse is that I was thinking that adding a new line note would put it at the end of the thread anyway. I didn't realize until I clicked on it that it would create a little sub-thread for the reply. It makes sense though, and seems handy. I'll use that next time.

I'm a perfectionist (:wink:)

Me too. I understand. 😆

mayamcdougall · 2016-04-29T17:14:09Z

try_files instead of the very complex location regex, fastcgi_split_path_info and if

So it's safe to remove fastcgi_split_path_info? I haven't tried that myself, but the point of the line seems to be to separate out any path following the .php file (example.com/index.php/some/url) and give it to PHP as a variable. Since Pico instead uses a query string internally, I can see why that wouldn't be needed. Just wanted to make sure there's no other purpose it might server for us.

Honestly, I've just been including the line because I've seen it a lot in examples... I don't actually know what purpose it serves on the PHP side of things or what that path information is used for. 😅

PhrozenByte · 2016-04-29T17:50:01Z

Yes, you can safely remove fastcgi_split_path_info. You can also use a much simpler regex like location ~ \.php$ { }.

The purpose of this directive is to imitate the PATH_INFO feature to allow SEO-like URLs out-of-the-box. PATH_INFO actually is part of the official CGI specification (see https://tools.ietf.org/html/rfc3875#section-4.1.5), but is practically limited to Apache (see https://httpd.apache.org/docs/2.2/mod/core.html#acceptpathinfo). Alternative webservers (like nginx - or IIS, lighttpd, httpd...)support PATH_INFO with workarounds only. Many configurations out there don't have those workarounds enabled. Thus it's usually a bad idea to use PATH_INFO. However, there are (better) alternatives - like QUERY_STRING.

mayamcdougall · 2016-05-04T16:11:02Z

sigh So I don't really have a better option for the denial rule at the moment. I added a little note about it in-case it causes issues. I don't really think it's worth the extra effort at this point when I'll probably have to rewrite half the document for 1.1 anyway.

In the future, a solution might be a location block containing all the Pico rules. Using a setup like that, there should be a way to state Pico's location once and have all the other rules conform to it.

I experimented a little while back with adding a separate root declaration inside of a location block and it did successfully change the $document_root variable inside the location block. The problem was that it didn't impact $uri at all. I think this was due to the change being after Nginx had created the $uri (it was inside the rewrite rule block).

Perhaps by declaring a Pico location with a new root, we could treat all the nested locations (the existing blocks) as if Pico were installed in Document Root. If this worked, we could potentially provide one Nginx example that would work no matter where Pico was installed. You'd enter Pico's location once and all subsequent rules would use it. This would also make all our rules affect only Pico, and eliminate the need to worry about interfering other software on the same virtual host.

Just speculating at the point, but it would be worth looking into in the future. 😄

Also, in regards to adding a new subsection to the document where Getting Started is... I'm not sure it's necessary. I'm just looking at the rendered page and imagining adding a new header. It feels a little redundant. There would only be two sections not inside it (Example Config and Advanced Tips), so it feels a bit like the entire document would be inside the new section. The document as a whole is about "Nginx Configuration", and every section in it is directly related to that topic (except for where I've already broken it down).

I don't know. As always, I'm open to any arguments you have in favor of it, I just don't think it adds any benefit right now.

And, I think that's everything. Let me know if I've forgotten to address any points we discussed.

And sorry for the extra long reply. 😅

PhrozenByte · 2016-05-06T21:24:33Z

Using root sounds promising, I look forward to your changes for Pico 1.1. I'm fine with not adding a superior section, it was just an idea. Maybe when you update the document for Pico 1.1. We'll see 😃

I've merged your PR with some very minor changes (see fa07158). 🎉 Thank you for your efforts @smcdougall, absolutely great work! 👍 😃

smcdougall added 2 commits April 20, 2016 20:08

Initial Commit for Nginx Documentation

8cdb956

Wrap Old Example Code in Code Block

d1f593d

mayamcdougall mentioned this pull request Apr 21, 2016

Improve Nginx Documentation #343

Closed

PhrozenByte added pri: Normal type: Enhancement info: Website labels Apr 21, 2016

PhrozenByte added this to the Version 1.0.3 milestone Apr 21, 2016

Repository owner locked and limited conversation to collaborators Apr 21, 2016

Repository owner unlocked this conversation Apr 21, 2016

PhrozenByte reviewed Apr 21, 2016
View reviewed changes

smcdougall added 3 commits April 21, 2016 13:48

Minor Revisions

8baaf61

Revised PHP example

6f09f66

PHP Example Warning

414a04f

PhrozenByte reviewed Apr 23, 2016
View reviewed changes

nginx.md

```

location / {

try_files $uri $uri/ /?$uri&$args

Copy link

Collaborator

PhrozenByte Apr 23, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing ';'

Missing ';'

84e3e8d

PhrozenByte reviewed Apr 23, 2016
View reviewed changes

mayamcdougall force-pushed the gh-pages branch from 9c40ee7 to 78764c8 Compare April 23, 2016 18:34

Code Block Indentation

fae6206

mayamcdougall force-pushed the gh-pages branch from 78764c8 to fae6206 Compare April 23, 2016 18:37

PhrozenByte force-pushed the gh-pages branch from 7fe731c to 96bf21b Compare April 27, 2016 12:18

PhrozenByte reviewed Apr 29, 2016
View reviewed changes

smcdougall added 2 commits April 29, 2016 10:52

Revisions

353a17b

Add files to 404 Rule

ed1b55b

PhrozenByte reviewed Apr 29, 2016
View reviewed changes

nginx.md

@@ -0,0 +1,192 @@

---

Copy link

Collaborator

PhrozenByte Apr 29, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please move the file to in-depth/nginx.md?

smcdougall added 3 commits April 29, 2016 12:44

Learn More... and php try_files

6f20b4b

Moved to in-depth/nginx.md

58345ef

Changed Nginx Page URL

643f52d

Revisions

a15a6ab

smcdougall and others added 2 commits April 29, 2016 14:46

Simplify PHP and sync examples

ac3995f

Added Note about denial rule

9aee47a

PhrozenByte merged commit 9a9e24e into picocms:gh-pages May 6, 2016

PhrozenByte added a commit that referenced this pull request May 6, 2016

Follow-up to 9a9e24e (merging pull request #345)

fa07158

PhrozenByte added status: Resolved and removed status: In Progress labels May 7, 2016

PhrozenByte mentioned this pull request May 19, 2016

Update Website & Documentation #323

Closed

16 tasks

mayamcdougall mentioned this pull request Jun 8, 2016

About Page & Fancybox / Portfolio Template #352

Merged

25 tasks

PhrozenByte mentioned this pull request Jan 27, 2018

Update Website & Documentation picocms/picocms.github.io#7

Open

19 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Nginx Documentation #345

Nginx Documentation #345

mayamcdougall commented Apr 21, 2016

PhrozenByte Apr 21, 2016

mayamcdougall commented Apr 21, 2016

PhrozenByte Apr 23, 2016

mayamcdougall commented Apr 23, 2016

PhrozenByte commented Apr 23, 2016

PhrozenByte Apr 23, 2016

mayamcdougall commented Apr 23, 2016 •

edited

Loading

mayamcdougall commented Apr 23, 2016 •

edited

Loading

PhrozenByte commented Apr 23, 2016

mayamcdougall commented Apr 23, 2016

PhrozenByte Apr 29, 2016 •

edited

Loading

mayamcdougall commented Apr 29, 2016

PhrozenByte Apr 29, 2016

mayamcdougall commented Apr 29, 2016 •

edited

Loading

mayamcdougall commented Apr 29, 2016

mayamcdougall commented Apr 29, 2016

mayamcdougall commented Apr 29, 2016

PhrozenByte commented Apr 29, 2016 •

edited

Loading

PhrozenByte Apr 29, 2016

mayamcdougall commented Apr 29, 2016

mayamcdougall commented Apr 29, 2016

PhrozenByte commented Apr 29, 2016

mayamcdougall commented May 4, 2016

PhrozenByte commented May 6, 2016 •

edited

Loading


		### Modular Pico Config

		Let's say you're a real Pico enthusiast and have several Pico websites running on the same server. You may get tired of writing all these rules into each and every server configuration. An easier solution might be to place all the common components (index, access denials, php rules) into a separate file and include it using `include /absolute/path/to/file`. You could also add the rewrite rule to this file, but a better option would be to include a second file, that way you can chose to include it only when Pico is located in your Document Root.

Nginx Documentation #345

Nginx Documentation #345

Conversation

mayamcdougall commented Apr 21, 2016

PhrozenByte Apr 21, 2016

Choose a reason for hiding this comment

mayamcdougall commented Apr 21, 2016

PhrozenByte Apr 23, 2016

Choose a reason for hiding this comment

mayamcdougall commented Apr 23, 2016

PhrozenByte commented Apr 23, 2016

PhrozenByte Apr 23, 2016

Choose a reason for hiding this comment

mayamcdougall commented Apr 23, 2016 • edited Loading

mayamcdougall commented Apr 23, 2016 • edited Loading

PhrozenByte commented Apr 23, 2016

mayamcdougall commented Apr 23, 2016

PhrozenByte Apr 29, 2016 • edited Loading

Choose a reason for hiding this comment

mayamcdougall commented Apr 29, 2016

PhrozenByte Apr 29, 2016

Choose a reason for hiding this comment

mayamcdougall commented Apr 29, 2016 • edited Loading

mayamcdougall commented Apr 29, 2016

mayamcdougall commented Apr 29, 2016

mayamcdougall commented Apr 29, 2016

PhrozenByte commented Apr 29, 2016 • edited Loading

PhrozenByte Apr 29, 2016

Choose a reason for hiding this comment

mayamcdougall commented Apr 29, 2016

mayamcdougall commented Apr 29, 2016

PhrozenByte commented Apr 29, 2016

mayamcdougall commented May 4, 2016

PhrozenByte commented May 6, 2016 • edited Loading

mayamcdougall commented Apr 23, 2016 •

edited

Loading

mayamcdougall commented Apr 23, 2016 •

edited

Loading

PhrozenByte Apr 29, 2016 •

edited

Loading

mayamcdougall commented Apr 29, 2016 •

edited

Loading

PhrozenByte commented Apr 29, 2016 •

edited

Loading

PhrozenByte commented May 6, 2016 •

edited

Loading