Deployment Overview of KVM with web management via Cockpit on Server¶

Prerequisites and Basic Requirements¶

To successfully deploy and access the application, the following conditions must be met on the server:

Operating System: A compatible Linux distribution capable of running Docker containers.
Privileges: Root or sudo privileges are required for Docker operations and configuration file management.
Network Access: The server must have outbound internet access to pull Docker images and perform SSL certificate validation.
Docker: Docker Engine and Docker Compose must be installed and running on the host system.
Domain: The server must be configured with a valid DNS entry under the hostkey.in domain.

FQDN of the Final Panel¶

The web management panel is accessible via the Fully Qualified Domain Name (FQDN) generated using the prefix kvm and the specific Server ID. The standard access URL format is:

kvm<Server ID>.hostkey.in:443

Replace <Server ID> with the actual numeric identifier of the server. The service listens on port 443 for HTTPS traffic.

File and Directory Structure¶

The deployment utilizes specific directories for configuration, certificates, and proxy settings. The key locations are:

/root/nginx/: Contains the Docker Compose configuration file for the proxy service.
/root/nginx/compose.yml: The primary orchestration file for the Nginx and Certbot containers.
/data/nginx/: The root directory for Nginx data and environment variables.
/data/nginx/user_conf.d/: Stores custom Nginx configuration files, specifically kvm<Server ID>.hostkey.in.conf.
/data/nginx/nginx-certbot.env: Environment file containing configuration for the Let's Encrypt client.
/etc/letsencrypt/: Volume mount point where SSL certificates are stored (mapped from nginx_secrets).

Application Installation Process¶

The application deployment relies on Docker containers orchestrated via Docker Compose. The installation process involves the following steps:

Ensure the /root/nginx directory exists on the host.
Deploy the proxy configuration file compose.yml into /root/nginx/.
Execute the Docker Compose command to start the Nginx and Certbot services in detached mode:
```
docker compose up -d
```
This command is executed within the /root/nginx directory.
The system automatically configures the Nginx proxy to forward traffic from the external interface to the internal application port 3000.

The deployment utilizes the Docker image jonasal/nginx-certbot:latest for both web serving and SSL certificate management.

Access Rights and Security¶

Security for the deployment is enforced through the following measures:

Firewall: External access is restricted to port 443 (HTTPS) as defined by the external port configuration.
SSL/TLS: All traffic is encrypted using Let's Encrypt certificates, which are automatically generated and renewed.
User Configuration: The Let's Encrypt client is configured to use the email address [email protected] for certificate notifications.
Container Isolation: The Nginx service runs in a container with the host network mode to facilitate direct port binding and internal communication.

Docker Containers and Their Deployment¶

The solution uses a single containerized service for the web proxy and certificate management. The container details are as follows:

Image: jonasal/nginx-certbot:latest
Restart Policy: unless-stopped
Network Mode: host
Volume Mounts:
nginx_secrets mapped to /etc/letsencrypt for certificate storage.
/data/nginx/user_conf.d mapped to /etc/nginx/user_conf.d for custom Nginx configurations.
Environment Variables:
CERTBOT_EMAIL: Set to [email protected].
Execution Command:
```
docker compose up -d
```

Proxy Servers¶

The deployment utilizes Nginx as the reverse proxy, managed through the jonasal/nginx-certbot Docker image. Key proxy settings include:

Parameter	Value	Description
Internal Host	`127.0.0.1`	Localhost IP used for proxying.
Internal Port	`3000`	The port where the application listens internally.
External Port	`443`	The port for secure HTTPS access.
External Path	`/`	Root path for the application.
Internal Path	`/`	Root path forwarded to the backend.
SSL Provider	Let's Encrypt	Automated SSL certificate issuance.
Email for Renewal	`[email protected]`	Contact email for certificate alerts.

The Nginx configuration located in /data/nginx/user_conf.d/kvm<Server ID>.hostkey.in.conf is automatically updated to include the proxy pass directive:

proxy_pass http://127.0.0.1:3000;

Permission Settings¶

File and directory permissions are set to ensure the Docker containers can access necessary resources:

/root/nginx:
Owner: root
Group: root
Mode: 0755 (Directory)
/root/nginx/compose.yml:
Owner: root
Group: root
Mode: 0644 (File)

The Nginx data directory /data/nginx and its subdirectories are assumed to be accessible by the host's Docker daemon with appropriate ownership to allow the container to read configuration files.

Location of Configuration Files and Data¶

All critical configuration files and data stores are located in the following paths:

Proxy Orchestration: /root/nginx/compose.yml
Custom Nginx Config: /data/nginx/user_conf.d/kvm<Server ID>.hostkey.in.conf
Environment Variables: /data/nginx/nginx-certbot.env
SSL Certificates: /etc/letsencrypt (accessible inside the container via the nginx_secrets volume)

Available Ports for Connection¶

The following ports are utilized by the deployed services:

Port 443: HTTPS traffic for the web management interface.
Port 3000: Internal port used by the application, accessible only via the local proxy within the host.

Starting, Stopping, and Updating¶

Service management is handled through Docker Compose commands executed in the /root/nginx directory.

Start/Restart Services:
```
cd /root/nginx
docker compose up -d
```
Stop Services:
```
cd /root/nginx
docker compose down
```
Update Services: To update the container image or configuration, pull the latest image and restart the stack:
```
cd /root/nginx
docker compose pull
docker compose up -d
```
Check Service Status:
```
docker compose ps
```