Deployment Overview of LinuxPatch Appliance on Server¶

Prerequisites and Basic Requirements¶

To successfully deploy the LinuxPatch Appliance, the host server must meet the following requirements:

Operating System: Linux distribution compatible with Docker Engine.
Privileges: Root access or sudo privileges are required to manage Docker services and configure the system.
Domain Configuration: The server must be configured to resolve the hostkey.in domain.
Ports: Ports 80 and 443 must be open on the host firewall to allow external traffic for the Nginx proxy and SSL termination.

FQDN of the Final Panel¶

The application is accessible via the following Fully Qualified Domain Name (FQDN) format:

linuxpatch<Server ID>.hostkey.in:443

Replace <Server ID> with the specific identifier assigned to the instance. The application is served over HTTPS on port 443.

File and Directory Structure¶

The deployment utilizes the following directory structure on the host system:

/root/linuxpatch: The primary installation directory containing the application source, configuration scripts, and Docker Compose files.
/root/linuxpatch/data: The data directory for the application, containing:
data/.env: Environment variables and credentials.
data/certs: SSL/TLS certificates.
data/logs: Application log files.
/data/nginx/user_conf.d: Directory containing Nginx user configuration files.
/etc/letsencrypt: Volume mount point for SSL certificates managed by Certbot.

Application Installation Process¶

The application is deployed using Docker Compose. The installation involves cloning the repository and executing a configuration script that generates necessary environment variables and Docker Compose definitions.

Clone the repository to the installation directory:

git clone https://github.com/linuxpatch/self-hosted.git /root/linuxpatch

Create the required Docker volume for Nginx secrets:
```
docker volume create nginx_secrets
```
Execute the configuration script located at /root/linuxpatch/configure.sh. This script:
Generates random credentials for the database, SMTP, and admin user.
Creates the data/.env file with configuration parameters.
Generates the docker-compose.yml file with the correct environment variables.
Starts the services automatically.

The application version is pulled dynamically using the linuxpatch/appliance:latest image tag.

Docker Containers and Their Deployment¶

The deployment consists of four main containers orchestrated via Docker Compose:

nginx:
Image: jonasal/nginx-certbot:latest
Function: Reverse proxy and SSL termination using Certbot.
Ports: Exposes 80 and 443 on the host.
Volumes: Mounts nginx_secrets for certificates and /data/nginx/user_conf.d for custom configurations.
linuxpatch-app:
Image: linuxpatch/appliance:latest
Function: The main LinuxPatch application service.
Command: ./web
Dependencies: Waits for linuxpatch-db and linuxpatch-redis to be healthy before starting.
Volumes: Mounts ./data to /app/data inside the container.
linuxpatch-db:
Image: percona/percona-server:8.0
Function: MySQL database server.
Volumes: Uses linuxpatch-mysql-data for persistent storage.
Health Check: Uses mysqladmin ping to verify service status.
linuxpatch-redis:
Image: redis:6
Function: Redis caching service.
Volumes: Uses linuxpatch-redis-data for persistent storage.
Health Check: Uses redis-cli ping to verify service status.

Databases¶

The application utilizes two database services running within the Docker network:

MySQL (Percona Server):
Service Name: linuxpatch-db
Connection Host: linuxpatch-db (internal Docker network)
Port: 3306
Database Name: Defined in data/.env as DB_NAME (default: linuxpatch).
Storage: Data is persisted in the linuxpatch-mysql-data Docker volume.
Redis:
Service Name: linuxpatch-redis
Connection Host: linuxpatch-redis (internal Docker network)
Port: 6379
Database Index: Defined in data/.env as REDIS_DATABASE (default: 0).
Storage: Data is persisted in the linuxpatch-redis-data Docker volume.

Proxy Servers¶

The deployment includes an Nginx container configured as a reverse proxy with SSL support:

Software: Nginx with Certbot (jonasal/nginx-certbot:latest).
SSL/TLS: Managed automatically via Certbot. Certificates are stored in the nginx_secrets volume.
Configuration: The proxy is configured to forward traffic to the linuxpatch-app container.
Custom Domain: The proxy is configured for the domain linuxpatch<Server ID>.hostkey.in.
Email for Certbot: Configured as [email protected].

Permission Settings¶

The following permission settings are applied during the deployment:

/root/linuxpatch: Owned by root:root with mode 0644.
/root/linuxpatch/configure.sh: Executable script with mode 0744.
data/certs and data/logs: Created with mode 755.
Docker volumes (linuxpatch-mysql-data, linuxpatch-redis-data, nginx_secrets) are managed by the Docker daemon and require root access to modify.

Location of Configuration Files and Data¶

All configuration and data files are located within the /root/linuxpatch directory:

Environment Variables: /root/linuxpatch/data/.env
Docker Compose Definition: /root/linuxpatch/docker-compose.yml
Configuration Script: /root/linuxpatch/configure.sh
SSL Certificates: Stored in the nginx_secrets volume (mounted at /etc/letsencrypt inside the Nginx container) and data/certs directory.
Application Logs: Stored in /root/linuxpatch/data/logs.

Available Ports for Connection¶

The following ports are exposed on the host server:

Port 80: HTTP traffic (redirected to HTTPS by Nginx).
Port 443: HTTPS traffic (secure access to the LinuxPatch panel).

Internal container communication occurs over the linuxpatch-app-network bridge network and is not exposed to the host.

Starting, Stopping, and Updating¶

Service management is handled via Docker Compose commands executed from the /root/linuxpatch directory:

Start Services:

cd /root/linuxpatch
docker compose up -d

Stop Services:

cd /root/linuxpatch
docker compose down

Update Application: To update the application to the latest version, pull the new images and restart the containers:
```
cd /root/linuxpatch
docker compose pull
docker compose up -d
```

View Logs:

cd /root/linuxpatch
docker compose logs -f