nginx/nginx/             # Maps directly to /etc/nginx/ on the server
├── nginx.conf           # Global settings (workers, gzip, TLS, logging)
├── conf.d/
│   ├── cloudflare_ips.conf   # Real-IP trust for Cloudflare ranges (auto-updated by cron)
│   ├── logging.conf          # Custom log formats (custom_format + json_analytics)
│   └── tuning.conf           # Performance tweaks (server_names_hash_bucket_size)
├── sites-available/     # One .conf file per logical group of sites
│   └── *.conf
├── sites-enabled/       # Symlinks to active configs in sites-available/
│   └── * -> ../sites-available/*.conf
└── ...                  # Standard nginx package files (mime.types, proxy_params, etc.)

Adding a New Site

Identify the right file. Each sites-available/*.conf has a comment at the top describing what belongs there. Pick the most appropriate file, or create a new one if the site does not fit anywhere.

Add the server block, following this template for a proxied app:

server {
  listen 443 ssl;
  server_name yourapp.nhcarrigan.com;
  ssl_certificate /etc/letsencrypt/live/yourapp.nhcarrigan.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/yourapp.nhcarrigan.com/privkey.pem;

  location / {
    proxy_set_header Host $host;
    proxy_pass http://127.0.0.1:<PORT>;
    proxy_redirect off;
  }
}

Or this template for a static site:

server {
  listen 443 ssl;
  server_name yoursite.nhcarrigan.com;
  ssl_certificate /etc/letsencrypt/live/yoursite.nhcarrigan.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/yoursite.nhcarrigan.com/privkey.pem;

  root /home/naomi/yoursite;

  location / {
    index index.html;
  }
}

Keep server blocks sorted alphabetically by server_name within the file. The CI sort check will fail if they are out of order. Note that hyphenated names sort before the bare domain in C locale (e.g. app-api before app).

If you created a new .conf file, create the corresponding symlink in sites-enabled/:

cd nginx/nginx/sites-enabled
ln -s ../sites-available/newfile.conf newfile.conf

Get the SSL certificate on the server before deploying:

sudo certbot certonly --nginx -d yourapp.nhcarrigan.com

Run the tests locally to verify everything passes:
```
bash test.sh
```
Deploy (see below).

Removing a Site

Delete the server block from the relevant sites-available/*.conf file.
If the entire .conf file is now empty, delete the file and its sites-enabled/ symlink.
Run bash test.sh to confirm nothing is broken.
Deploy.

Deploying Changes

Push the local nginx/nginx/ directory to the server (the --delete flag removes any files on the server that no longer exist locally):

bash push.sh

Then reload nginx to apply the changes:

ssh prod "sudo systemctl reload nginx"

To pull the current server config back into this repository:

bash pull.sh

Testing

The test suite runs static analysis checks against the config files without requiring a live nginx instance:

bash test.sh

The following checks are run:

#	Check
1	No deprecated TLS versions (TLSv1 / TLSv1.1)
2	No duplicate `server_name` values
3	Every `sites-available/*.conf` has a `sites-enabled` symlink
4	No broken symlinks in `sites-enabled`
5	No orphaned symlinks in `sites-enabled`
6	No port-80 listeners in custom server blocks
7	`ssl_certificate` and `ssl_certificate_key` counts match per file
8	All plain-HTTP `proxy_pass` targets are local
9	All SSL cert paths use `/etc/letsencrypt/live/`
10	Certs use `fullchain.pem` / keys use `privkey.pem`
11	No raw IP addresses as `server_name`
12	`conf.d` contains only expected files
13	Server blocks are sorted alphabetically by `server_name` within each file

CI additionally runs an nginx syntax check (nginx -t) using stub SSL certificates, catching any configuration errors that static analysis cannot detect.

Feedback and Bugs

If you have feedback or a bug report, please log a ticket on our forum.

Contributing

If you would like to contribute to the project, you may create a Pull Request containing your proposed changes and we will review it as soon as we are able! Please review our contributing guidelines first.

Code of Conduct

Before interacting with our community, please read our Code of Conduct.

License

This software is licensed under our global software license.

Contact

We may be contacted through our Chat Server or via email at contact@nhcarrigan.com.