As explained in our parent article, we love Nginx. In order to create similar working environments on both your local machine as your server(s), we've written 2 sibling articles as close aligned as possible.
OSX comes with Apache pre-installed. Lovely.
Now we need to ignore that. As with every http server flavour, Nginx has its on set of quirks. After years of .htaccess hacking, we're sure you'll find some use in the latter tricks and modifications.
Setup
For your local convenience
If you don't have HomeBrew installed, go get it already: homebrew article. If you have, it doesn't hurt to update to the latest version.
$ brew update
$ brew upgrade --all
The actual install of Nginx on OSX takes seconds:
$ brew install nginx
To make sure everything went fine, you can run $ brew doctor
The configuration is located at /usr/local/etc/nginx/nginx.conf, and will need some tweaking if you want to use Nginx as default webserver and maybe add php.
Auto start
We'll want Nginx to listen to the default port 80, which requires root credits. Let's set this up, softlink the plist to the auto start directory and launch a root'ed process.
First check if the /Library/LaunchAgents exists, you might need to create it:
$ mkdir -p /Library/LaunchDaemons
$ sudo cp /usr/local/opt/nginx/*.plist /Library/LaunchDaemons
$ sudo chown root:wheel /Library/LaunchDaemons/homebrew.mxcl.nginx.plist
$ sudo launchctl load -w /Library/LaunchDaemons/homebrew.mxcl.nginx.plist
If you haven't tweaked the config files yet, you can test the process with curl on the default Nginx port.
curl -IL http://localhost:80
Let's abort the service for now. Yes, you can just run nginx, the -s stand for "Signal the master process" and accepts stop, quit, reopen or reload.
$ sudo nginx -s stop
Server-like config
You probably want your local environment behaving as close as possible as your server setup. Let's add some folders first. Be careful with the rights, if you already have /var/www, ignore those actions, or you might have to re-commit ALL your git repos stored there.
$ cd /usr/local/etc/nginx
$ mkdir -p sites-available sites-enabled conf.d global
$ sudo mkdir -p /var/www
$ sudo chown :staff /var/www
$ sudo chmod 775 /var/www
Now let's clean out the main config file. It looks a bit different then the server version.
You can simply clean and replace.
$ sudo nano /usr/local/etc/nginx/nginx.conf
worker_processes 1;
events {
worker_connections 768;
}
http {
include mime.types;
default_type application/octet-stream;
types_hash_max_size 2048;
sendfile on;
keepalive_timeout 45;
error_log /usr/local/var/log/nginx/error.log debug;
access_log /usr/local/var/log/nginx/access.log;
include conf.d/*.conf;
include sites-enabled/*;
}
We configure more project-specific settings next.
NODE
Nginx is very suited to proxy your local url's to Node, like Ghost.
You of course need Node installed: frontend article.
PHP-FPM
You'll probably going to use php along the line. PHP-FPM is our poison of choice, as it is on the server. Prepare the brew, or ignore this install if you're a Node- or Python-head.
$ brew tap homebrew/dupes
$ brew tap josegonzalez/homebrew-php
Install without Apache. This can take a couple of minutes. This article is based on php5.5, your machine might have an alternative version - edit accordingly.
$ brew install --without-apache --with-fpm --with-mysql php55
All you need now is an auto-start, make sure you link the right version (replace the 5.5.xx by your temporary one). Then launch PHP-FPM.
$ ln -s /usr/local/Cellar/php55/5.5.xx/homebrew.mxcl.php55.plist ~/Library/LaunchAgents/
$ launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.php55.plist
To confirm a responsive port 9000, lsof -Pni4 | grep LISTEN | grep php should put out something like this:
php-fpm 68817 user 6u IPv4 0x3d7bc2124072d59b 0t0 TCP 127.0.0.1:9000 (LISTEN)
php-fpm 68818 user 0u IPv4 0x3d7bc2124072d59b 0t0 TCP 127.0.0.1:9000 (LISTEN)
php-fpm 68819 user 0u IPv4 0x3d7bc2124072d59b 0t0 TCP 127.0.0.1:9000 (LISTEN)
php-fpm 68820 user 0u IPv4 0x3d7bc2124072d59b 0t0 TCP 127.0.0.1:9000 (LISTEN)
Config Files
We have a couple of boilerplate configuration files for easy vhost addition.
General
Some global configurations are stored in global/general.conf and included in some of our vhosts. Go ahead and create it.
$ nano /usr/local/etc/nginx/global/general.conf
# Global configuration http file.
# Designed to be included in any server {} block.
listen 80;
rewrite ^(.+)/+$ $1 permanent;
location = /favicon.ico {
log_not_found off;
access_log off;
}
location = /robots.txt {
allow all;
log_not_found off;
access_log off;
}
# Deny all attempts to access hidden files such as .htaccess or .DS_Store
# Keep logging the requests to parse later (or to pass to firewall utilities such as fail2ban)
location ~ /\. {
deny all;
}
# Directives to send expires headers and turn off 404 error logging.
location ~* ^.+\.(ogg|ogv|svg|svgz|eot|otf|woff|mp4|ttf|rss|atom|jpg|jpeg|gif|png|ico|zip|tgz|gz|rar|bz2|tar|mid|midi|wav|bmp|rtf)$ {
expires max;
log_not_found off;
access_log off;
}
PHP FastCGI
If you're using PHP, You'll need to pass the scripts to the FastCGI server listening on the port 9000.
This setup varies between your local and server environment. Obviously, ignore this file if you're never going to use PHP. We've added it in the global/laravel.conf file. You might want to store it in conf.d/php-fpm.conf otherwise, for default addition.
server {
location ~ \.php$ {
try_files $uri = 404;
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
include fastcgi.conf;
}
}
Important: You should have cgi.fix_pathinfo = 0; in your php.ini at all times.
Laravel
Laravel and Nginx play well together. This global conf is tailored to be included in all your Laravel (and Lumen) projects as global/laravel.conf.
# Laravel php rules.
# Designed to be included in any server {} block.
# Use alongside global/general.conf
index index.php;
try_files $uri $uri/ @rewrite;
location @rewrite {
rewrite ^/(.*)$ /index.php?_url=/$1;
}
error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include /usr/local/etc/nginx/fastcgi.conf;
break;
}
Wordpress
Wordpress is one of the older kids who's actually more used to play with Apache, so we'll need to set up some specific rules to keep it's behaviour predicatble. Nano global/wordpress.conf:
# WordPress single blog rules.
# Designed to be included in any server {} block.
# Use alongside global/general.conf
index index.php;
# Deny access to any files with a .php extension in the uploads directory
location ~* /(?:uploads|files)/.*\.php$ {
deny all;
}
location / {
try_files $uri $uri/ /index.php?$args;
}
# Add trailing slash to */wp-admin requests.
rewrite /wp-admin$ $scheme://$host$uri/ permanent;
Vhosts
Your projects
Your vhost file is basicly your website directive, stored in sites-available. The configuration varies wildly, depending on your flavour of choice. We've added some examples.
Create project
As you might have guessed, you should start with creating your project root.
$ mkdir /var/www/html/project
Add vhosts
To add a vhost site, it's a good practise to add a file to sites-available and link it in sites-enabled. We'll describe the file's content later on.
$ nano /usr/local/etc/nginx/sites-available/project
$ ln -s /usr/local/etc/nginx/sites-available/project /usr/local/etc/nginx/sites-enabled/project
The possible configurations (to be included in the above):
Static project
Static projects (eg. a Grunt-generated web app) are usually pre-compiled and nimble in use. This should be reflected in the config file too.
server {
server_name project.local;
root /var/www/html/project/staging;
include /usr/local/etc/nginx/global/general.conf;
index index.html;
location / {
try_files $uri $uri.html $uri/ /index.html;
}
}
Ghost project
If you want to add a ghost blog, you just need to proxy your site to the running ghost server.
Your file contents will look like this (port 2368 is your default Ghost port):
server {
listen 80;
server_name project.com;
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header HOST $http_host;
proxy_set_header X-NginX-Proxy true;
proxy_pass http://127.0.0.1:2368;
proxy_redirect off;
}
}
Laravel project
To set up a Laravel (or Lumen) project, the nginx configuration file needs a couple of extra lines. We use php-fpm in this example.
server {
server_name project.com;
root /var/www/html/project/public;
# Laravel configuration
include global/general.conf;
include global/laravel.conf;
}
Wordpress project
Who hasn't hosted a Wordpress website before, right? The default vhost entry points to the project root (we use project/www) and include the previously explained configurations.
server {
server_name project.com;
root /var/www/html/project/www;
# Wordpress configuration
include global/general.conf;
include global/wordpress.conf;
}
And as always, reload your nginx files.
$ sudo nginx -s reload
Notes
Set your custom local url
It’s very simple to point custom made urls to your local environment. Open /etc/hosts as admin and add a name to your liking:
$ sudo nano /etc/hosts
> 127.0.0.1 project-api.local
Add some aliases
We've enabled a set of services we probably want to start/stop/reload in the future. OSX has aliases for just that.
$ nano /tmp/.aliases
### Service Aliases - Nginx
alias nginx.logs.error='tail -200f /usr/local/var/log/nginx/error.log'
alias nginx.logs.access='tail -200f /usr/local/var/log/nginx/access.log'
### Service Aliases - PHP-FPM
alias php-fpm.start="sudo launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.php55.plist"
alias php-fpm.stop="sudo launchctl unload -w ~/Library/LaunchAgents/homebrew.mxcl.php55.plist"
alias php-fpm.restart='php-fpm.stop && php-fpm.start'
Let's add it to your user profile and reload.
$ cat /tmp/.aliases >> ~/.profile
$ source ~/.profile