Deployment Overview of NATS on Server¶

Prerequisites and Basic Requirements¶

The deployment of NATS requires a Linux environment, specifically Ubuntu, with the following prerequisites:

• Operating System: Ubuntu
• Privileges: Root access is required to manage Docker, systemd services, and file permissions.
• Docker Engine: The Docker service must be installed and running on the host.
• Ports:
• 4222: Client listener port for NATS.
• 8222: Monitoring HTTP port for NATS status and metrics.
• 80 and 443: Required for the Nginx proxy and Let's Encrypt certificate management.

File and Directory Structure¶

The application utilizes specific directories for configuration, data storage, and proxy management. The following paths are established on the server:

• NATS Configuration: Located at the path defined by the nats_conf_file variable (typically within /etc/nats/ or a custom directory).
• NATS Data Directory: Located at the path defined by the nats_data_dir variable, used for general data storage.
• JetStream Storage: If JetStream is enabled, data is stored in the directory defined by nats_js_store_dir.
• Nginx Configuration:
• Main directory: /root/nginx
• User configuration files: /data/nginx/user_conf.d
• Environment variables: /data/nginx/nginx-certbot.env
• SSL Certificates: Stored in the external Docker volume nginx_secrets mounted at /etc/letsencrypt.

Application Installation Process¶

NATS is deployed as a Docker container managed by a systemd service. The installation process involves the following components:

• Docker Image: The system pulls the NATS image specified by the nats_image variable.
• Container Name: The container is identified by the nats_container_name variable.
• Configuration File: A configuration file is generated containing:
• Client listener on port 4222.
• HTTP monitoring on port 8222.
• Authorization settings, which can be configured for either token-based authentication or username/password authentication.
• JetStream settings, including memory and file store limits, if enabled.

The systemd unit file is created at /etc/systemd/system/nats.service to manage the lifecycle of the NATS container.

Docker Containers and Their Deployment¶

The NATS service runs within a Docker container with the following specifications:

• Container Execution: The container is started with the --rm flag, ensuring it is removed upon stop.
• Port Mapping:
• Host port {{ nats_client_port }} maps to container port 4222.
• Host port {{ nats_http_port }} maps to container port 8222.
• Volume Mounts:
• The NATS configuration file is mounted read-only at /etc/nats/nats-server.conf.
• The data directory is mounted at /data.
• Startup Command: The container executes the NATS server with the configuration file: -c /etc/nats/nats-server.conf.

The systemd service handles the removal of any existing container with the same name before starting a new instance.

Proxy Servers¶

A reverse proxy is deployed using Docker Compose to handle SSL termination and routing for the NATS monitoring interface.

• Proxy Image: jonasal/nginx-certbot:latest
• Deployment Method: Managed via docker compose in the /root/nginx directory.
• Configuration:
• The proxy uses the host network mode.
• It mounts the nginx_secrets volume for Let's Encrypt certificates.
• User-specific configuration files are mounted from /data/nginx/user_conf.d.
• Routing:
• The proxy is configured to forward requests to the NATS monitoring interface at http://127.0.0.1:8222.
• The configuration file for the host is located at /data/nginx/user_conf.d/{{ prefix }}{{ server_id }}.hostkey.in.conf.
• Certificate Management:
• Certbot is integrated to automatically obtain and renew SSL certificates.
• The email address for certificate notifications is set to [email protected].

Permission Settings¶

File and directory permissions are set to ensure secure operation:

• Nginx Directory: /root/nginx is owned by root with permissions 0755.
• Docker Compose File: /root/nginx/compose.yml is owned by root with permissions 0644.
• NATS Configuration File: Set to permissions 0644.
• NATS Directories: Configuration and data directories are created with permissions 0755.
• Systemd Unit File: /etc/systemd/system/nats.service is set to permissions 0644.

Starting, Stopping, and Updating¶

The NATS service is managed using systemctl commands, while the proxy is managed via Docker Compose.

• Start NATS Service:

  systemctl start nats
  

• Stop NATS Service:

  systemctl stop nats
  

• Restart NATS Service:

  systemctl restart nats
  

• Enable NATS on Boot:

  systemctl enable nats
  

• Reload Systemd Daemon:

  systemctl daemon-reload
  

For the Nginx proxy, the following commands are used in the /root/nginx directory:

• Start/Update Proxy:

  docker compose up -d
  

• Stop Proxy:

  docker compose down
  

The systemd service automatically pulls the latest NATS image if an update is available and restarts the container if the configuration or unit file has changed.