Skip to main content
The nginx.sh script provides comprehensive management capabilities for the nginx reverse proxy, including configuration testing, log viewing, SSL certificate management, and real-time monitoring.

​
Location

scripts/nginx.sh

​
Usage

./scripts/nginx.sh <command> [options]
All commands verify the nginx container is running before execution and provide color-coded output for better readability.

​
Container Status

​
status

Display the current status of the nginx container. 
./scripts/nginx.sh status
Example output: 
[INFO] nginx container status:
NAMES    STATUS          PORTS
nginx    Up 2 hours      0.0.0.0:8000->8080/tcp

​
Log Management

​
logs

Show nginx container logs. 
./scripts/nginx.sh logs [lines]
​
lines
string
default:"50"
Number of log lines to display. Use all for follow mode with all logs.
Examples: 
# Show last 50 lines (default)
./scripts/nginx.sh logs

# Show last 100 lines
./scripts/nginx.sh logs 100

# Show all logs in follow mode (Ctrl+C to exit)
./scripts/nginx.sh logs all

​
access-log

Show nginx access log entries. 
./scripts/nginx.sh access-log [lines]
​
lines
number
default:"50"
Number of access log lines to display.
Example: 
./scripts/nginx.sh access-log 100
Example output: 
192.168.1.100 - - [04/Mar/2026:12:00:00 +0000] "GET /health HTTP/1.1" 200 15
192.168.1.101 - - [04/Mar/2026:12:00:01 +0000] "POST /api/v1/machine HTTP/1.1" 200 1234

​
error-log

Show nginx error log entries. 
./scripts/nginx.sh error-log [lines]
​
lines
number
default:"50"
Number of error log lines to display.
Example: 
./scripts/nginx.sh error-log 100

​
Configuration Management

​
test

Test nginx configuration syntax without restarting. 
./scripts/nginx.sh test
Example output: 
[INFO] Testing nginx configuration...
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
[INFO] Configuration test passed!
Always test configuration before reloading to prevent downtime from syntax errors.

​
reload

Reload nginx configuration without dropping connections. 
./scripts/nginx.sh reload
Example: 
./scripts/nginx.sh reload
# [INFO] Reloading nginx configuration...
# [INFO] nginx configuration reloaded successfully!
Reloading gracefully applies configuration changes without downtime. Active connections continue while new connections use the updated configuration.

​
restart

Restart the entire nginx container. 
./scripts/nginx.sh restart
Example: 
./scripts/nginx.sh restart
# [INFO] Restarting nginx container...
# [INFO] nginx container restarted successfully!
Restarting drops all active connections. Use reload when possible for zero-downtime updates.

​
Health and Monitoring

​
health

Check the Headscale health endpoint through nginx. 
./scripts/nginx.sh health
Example output: 
[INFO] Checking health endpoint...
[INFO] Health check passed! (HTTP 200)
The script tests:
  • Development mode: http://localhost:8000/health
  • Production mode: Warns if endpoint is not accessible
In production mode with HTTPS, the health endpoint may not be accessible from localhost. This is expected behavior.

​
stats

Show nginx container resource usage statistics. 
./scripts/nginx.sh stats
Example output: 
[INFO] nginx container statistics:
CONTAINER  CPU %   MEM USAGE / LIMIT    MEM %   NET I/O         BLOCK I/O
nginx      0.02%   12.5MiB / 7.775GiB   0.16%   1.2MB / 856kB   0B / 0B

​
connections

Show the number of active connections to nginx. 
./scripts/nginx.sh connections
Example output: 
[INFO] Active connections to nginx:
5
This counts connections on port 8080 (internal). Use this to monitor current load.

​
top

Show real-time resource usage for nginx. 
./scripts/nginx.sh top
Example: 
./scripts/nginx.sh top
# [INFO] Real-time resource usage (Ctrl+C to exit):
# Updates every 2 seconds with live CPU, memory, and network stats
Press Ctrl+C to exit the real-time view.

​
SSL Certificate Management

​
ssl-info

Display SSL certificate information (production only). 
./scripts/nginx.sh ssl-info
Example output: 
[INFO] SSL certificate information:
Validity
    Not Before: Mar  1 00:00:00 2026 GMT
    Not After : May 30 23:59:59 2026 GMT
Subject: CN = headscale.yourdomain.com
Issuer: C = US, O = Let's Encrypt, CN = R3
This command only works in production mode with Let’s Encrypt certificates mounted. In development mode, it will show a warning.

​
ssl-test

Test SSL/TLS configuration using OpenSSL. 
./scripts/nginx.sh ssl-test [domain]
​
domain
string
default:"localhost"
The domain to test SSL configuration for.
Example: 
./scripts/nginx.sh ssl-test headscale.yourdomain.com
Requires OpenSSL to be installed on the host system. Tests the SSL connection and displays certificate details.

​
Advanced Commands

​
exec

Execute arbitrary commands inside the nginx container. 
./scripts/nginx.sh exec <command>
​
command
string
required
The shell command to execute inside the nginx container.
Examples: 
# List configuration files
./scripts/nginx.sh exec "ls -la /etc/nginx/"

# Check nginx version
./scripts/nginx.sh exec "nginx -v"

# View running processes
./scripts/nginx.sh exec "ps aux"

# Check disk space
./scripts/nginx.sh exec "df -h"
Use this command carefully. Direct container access can affect running services.

​
Help Command

Display the help message with all available commands. 
./scripts/nginx.sh help
# or
./scripts/nginx.sh --help
# or
./scripts/nginx.sh -h

​
Common Workflows

​
Update Configuration

# 1. Edit the configuration file
vim nginx.conf

# 2. Test the new configuration
./scripts/nginx.sh test

# 3. If test passes, reload nginx
./scripts/nginx.sh reload

# 4. Verify health
./scripts/nginx.sh health

​
Troubleshoot Connection Issues

# 1. Check container status
./scripts/nginx.sh status

# 2. View recent errors
./scripts/nginx.sh error-log 100

# 3. Test health endpoint
./scripts/nginx.sh health

# 4. Check active connections
./scripts/nginx.sh connections

# 5. View access patterns
./scripts/nginx.sh access-log 50

​
Monitor Performance

# View current resource usage
./scripts/nginx.sh stats

# Monitor in real-time
./scripts/nginx.sh top

# Check connection count
./scripts/nginx.sh connections

​
SSL Certificate Verification

# Check certificate details
./scripts/nginx.sh ssl-info

# Test SSL connection
./scripts/nginx.sh ssl-test headscale.yourdomain.com

# View SSL-related errors
./scripts/nginx.sh error-log 100 | grep -i ssl

​
Color-Coded Output

The script uses color coding for clarity:
  • Green [INFO]: Informational messages and success
  • Yellow [WARN]: Warnings and non-critical issues
  • Red [ERROR]: Errors and critical failures

​
Error Handling

The script exits with an error if:
  • nginx container is not running (checked before most commands)
  • Configuration test fails
  • Reload or restart operations fail
  • Required tools (like OpenSSL for SSL tests) are missing

​
Container Check

Most commands verify the nginx container is running: 
if ! docker ps --filter "name=nginx" --filter "status=running" | grep -q "nginx"; then
    error "nginx container is not running"
    exit 1
fi

​
Log Locations

Nginx logs are stored inside the container:
  • Access log: /var/log/nginx/access.log
  • Error log: /var/log/nginx/error.log
Access these using the access-log, error-log, or exec commands.

​
Direct Docker Access

For operations not covered by the script: 
# View logs directly
docker logs nginx

# Execute commands
docker exec nginx <command>

# Restart using Docker Compose
docker compose restart nginx

​
Development vs Production Mode

The script adapts to different deployment modes: Development Mode (HTTP on port 8000):
  • Health checks use http://localhost:8000/health
  • No SSL certificate checks
  • Simpler configuration
Production Mode (HTTPS on port 443):
  • SSL certificate information available
  • SSL testing capabilities
  • Rate limiting and security headers
  • Health endpoint may not be accessible from localhost

Build docs developers (and LLMs) love

Get started for freeTalk to us