{
  "id": "nginx-config",
  "title": "nginx Configuration",
  "category": "web",
  "tags": ["nginx", "config", "syntax", "reload", "vhost"],
  "updated": "2025-09-18",
  "summary": "nginx config structure, common syntax errors, and safe reload procedure.",
  "sections": [
    {
      "heading": "Config File Layout",
      "body": "<p>nginx uses a block-based config syntax. The main file is <code>/etc/nginx/nginx.conf</code>. Site configs live in <code>/etc/nginx/sites-available/</code> and are symlinked into <code>/etc/nginx/sites-enabled/</code> to activate them.</p><p>Every block opens with <code>{</code> and closes with <code>}</code>. Every directive ends with <code>;</code>. Missing either one will fail the syntax check.</p>"
    },
    {
      "heading": "Testing Config Before Reloading",
      "body": "<p>Always test before reloading. A bad config will prevent nginx from reloading, but it will <em>not</em> take down the running process—the old config stays live.</p>",
      "code": "nginx -t\n# or\nnginx -T   # prints the full parsed config"
    },
    {
      "heading": "Reloading vs Restarting",
      "body": "<p>Use reload, not restart. Reload applies the new config without dropping existing connections.</p>",
      "code": "systemctl reload nginx\n\n# Only use restart if you have to—it drops active connections.\nsystemctl restart nginx"
    },
    {
      "heading": "Common Syntax Errors",
      "body": "<ul><li>Missing semicolon at the end of a directive</li><li>Missing closing brace <code>}</code> on a block</li><li>Typo in a directive name (nginx will report \"unknown directive\")</li><li>Referencing a cert file or log path that does not exist</li><li>Duplicate <code>listen</code> directives on the same port across multiple vhosts without <code>default_server</code> resolution</li></ul><p>The error message from <code>nginx -t</code> includes the file name and line number. Read it.</p>"
    },
    {
      "heading": "Useful Log Paths",
      "body": "<p>Default paths on Debian/Ubuntu:</p>",
      "code": "/var/log/nginx/error.log\n/var/log/nginx/access.log\n\n# Per-vhost logs are usually defined in the server block:\naccess_log /var/log/nginx/mysite.access.log;\nerror_log  /var/log/nginx/mysite.error.log;"
    },
    {
      "heading": "Quick Vhost Template",
      "body": "<p>Minimal working vhost for a static site:</p>",
      "code": "server {\n    listen 80;\n    server_name example.internal;\n\n    root /var/www/example;\n    index index.html;\n\n    location / {\n        try_files $uri $uri/ =404;\n    }\n\n    access_log /var/log/nginx/example.access.log;\n    error_log  /var/log/nginx/example.error.log;\n}"
    }
  ]
}