DOCSEARCHbyAlgolia
Submit Docs

nginx ignition

repository·main·Indexed 24 days ago

https://github.com/lucasdillmann/nginx-ignition

A modern user interface for the nginx web server providing control over virtual hosts, streams, routing, and security. Key features include automated Let's Encrypt (ACME) and custom SSL certificate management, TCP/UDP/Unix socket proxying, and native integrations with Docker, Tailscale, and NetBird. It supports multiple installation methods including Docker, Docker Compose, and native packages for Debian, Ubuntu, RedHat, Fedora, Alpine, Arch Linux, OpenWrt, Windows, and macOS.

Tokens
13.8K
Snippets
20
Records
69
Agent score
84%

What's inside nginx-ignition

  1. Overview of nginx ignition features

    main

    nginx ignition is a modern user interface for the nginx web server designed for developers and enthusiasts. Key capabilities include:

    • Virtual hosts: Manage multiple hosts with custom domains, routes, and port bindings.
    • Streams: Proxy TCP, UDP, and Unix sockets with SNI-based routing, circuit breakers, and load balancing.
    • Versatile routing: Configure proxies, redirections, custom JS/Lua code, static responses, or file serving.
    • Server configuration: Manage nginx settings like maximum body size, server tokens, timeouts, and log levels.
    • SSL certificates: Automated Let's Encrypt (ACME), self-signed, or custom certificates.
    • Native integrations: Support for Docker, Docker Swarm, Tailscale, NetBird VPNs, and TrueNAS.
    • Security: Two-factor authentication (2FA), attribute-based access control (ABAC), and per-host access lists (basic auth and source IP checks).
    • Logging & Stats: Detailed access/error logs with rotation and real-time traffic statistics (request rates, response times, etc.).
    • Caching: Built-in nginx caching configuration.
    • Execution modes: Can run nginx directly or simply generate configuration files.

  2. Connect to a PostgreSQL database

    main

    While nginx ignition includes an embedded SQLite database, it is strongly recommended to use a PostgreSQL database for long-term installations.

    To connect to PostgreSQL, configure the following environment variables:

    • NGINX_IGNITION_DATABASE_DRIVER: Set to postgres.
    • NGINX_IGNITION_DATABASE_HOST: The hostname or IP of the database server.
    • NGINX_IGNITION_DATABASE_PORT: The database port.
    • NGINX_IGNITION_DATABASE_NAME: The name of the database.
    • NGINX_IGNITION_DATABASE_SSL_MODE: Set to require or disable (defaults to require).
    • NGINX_IGNITION_DATABASE_USERNAME: The database username.
    • NGINX_IGNITION_DATABASE_PASSWORD: The database password.

    nginx ignition will automatically create all required tables and indexes upon booting and will apply schema changes automatically during future updates.

    NGINX_IGNITION_DATABASE_DRIVER=postgres
NGINX_IGNITION_DATABASE_HOST=192.168.1.150
NGINX_IGNITION_DATABASE_PORT=5432
NGINX_IGNITION_DATABASE_NAME=my_custom_db
NGINX_IGNITION_DATABASE_SSL_MODE=disable
NGINX_IGNITION_DATABASE_USERNAME=my_username
NGINX_IGNITION_DATABASE_PASSWORD=supersecretpassword

  3. Migrate from nginx ignition 1.x to 2.0.0

    main

    Version 2.0.0 introduces breaking changes to how database connections are configured.

    Important Database Note:

    • In version 1.x, the embedded database was H2. In version 2.0.0, it was changed to SQLite.
    • Migration is NOT possible if you are using the embedded database.
    • Migration is only supported if you are using a PostgreSQL database.

  4. Configure Kubernetes liveness and readiness probes

    main

    For Kubernetes deployments, it is recommended to configure both liveness and readiness probes using the provided endpoints on port 8090.

    livenessProbe:
  httpGet:
    path: /api/health/liveness
    port: 8090
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /api/health/readiness
    port: 8090
  initialDelaySeconds: 5
  periodSeconds: 10

  5. Install nginx ignition via native packages

    main

    You can download native packages for various operating systems and architectures from the releases page. Supported platforms include:

    • Debian, Ubuntu: .deb (amd64, arm64)
    • RedHat, Fedora: .rpm (amd64, arm64)
    • Alpine Linux: .apk (amd64, arm64)
    • Arch Linux: .pkg.tar.zst (amd64, arm64)
    • OpenWrt: .ipk (amd64, arm64)
    • Windows: ZIP archive (amd64, arm64)
    • macOS: ZIP archive (arm64)

  6. Restore an SQLite database

    main

    If you are using the default embedded SQLite database, your backup is a single .db file named nginx-ignition.db.

    Important Safety Notes:

    • Stop the application (or container) before restoring to prevent data corruption caused by simultaneous writes.
    • Always keep a backup copy of your current database before overwriting it.

    Default Path: The official Docker image expects the file at /opt/nginx-ignition/data/nginx-ignition.db. You can change this location using the NGINX_IGNITION_DATABASE_DATA_PATH environment variable.

  7. Use a configuration file for nginx ignition

    main

    Instead of using environment variables, you can configure nginx ignition using a properties file. The application looks for configuration in the following order of precedence:

    1. The file path specified by the NGINX_IGNITION_CONFIG_FILE_PATH environment variable.
    2. The path provided via the --config command line argument.
    3. A file named nginx-ignition.properties located in the current working directory.

  8. Configure Docker Compose health checks

    main

    To monitor container health in Docker Compose, use the liveness endpoint within the healthcheck configuration. The following example uses curl to check the endpoint on port 8090.

    services:
  nginx-ignition:
    image: nginx-ignition:latest
    ports:
      - "8090:8090"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8090/api/health/liveness"]
      interval: 30s
      timeout: 3s
      start_period: 5s
      retries: 3

  9. Install nginx ignition via Docker Compose

    main
    For a production-ready setup, it is recommended to use Docker Compose. This method allows you to easily include a PostgreSQL database and configure health checks for your instance. You can find the official configuration in the docker-compose.yml file in the repository root.

  10. Quick test with Docker

    main

    To quickly test nginx ignition without a full installation, you can run it using a single Docker command. This will start the application and expose the web interface on port 8090.

    1. Run the Docker command provided below.
    2. Wait a few seconds for initialization.
    3. Open http://localhost:8090 in your browser.
    4. Follow the setup wizard to create your first user.

    Note: By default, an embedded SQLite database is used. For production environments, it is recommended to use PostgreSQL.

    docker run -p 8090:8090 -p 80:80 dillmann/nginx-ignition

  11. Restore a PostgreSQL database

    main

    If you are using a PostgreSQL server, your backup is a plain .sql file.

    Prerequisites:

    • You must have a running, empty PostgreSQL database.
    • You must have a user with privileges to create, alter, and drop objects.
    • You may need to install the psql client locally.

    Safety Note: Stop the nginx-ignition application/container before performing the restore to avoid write conflicts.

  12. Define a custom authentication token secret

    main

    nginx ignition uses JSON Web Tokens (JWT) for user authentication. To ensure users remain logged in across application restarts, you should define a persistent JWT secret using the NGINX_IGNITION_SECURITY_JWT_SECRET environment variable.

    Requirements:

    • The value must be a string exactly 64 characters long.

    If no value is provided, the application generates a random value on every boot, which will force all users to log in again whenever the app restarts.

    NGINX_IGNITION_SECURITY_JWT_SECRET="e54rVg9NX5moIP6k2xmUwT0bauAG7pvkR7XI7ygJ6jz0T50huvujCdW4ym6mOjAy"