Deployment Overview of LinuxPatch Appliance on Server¶

Prerequisites and Basic Requirements¶

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

Operating System: Linux distribution compatible with Docker Engine.
Privileges: Root access or a user with sudo privileges to manage Docker containers and system directories.
Docker Engine: Installed and running on the host system.
Docker Compose: Installed to manage multi-container applications.
Network Access: The server must be reachable via a domain name or hostname for SSL certificate generation and application access.
Ports: Ports 80 and 443 must be open on the host firewall for HTTP and HTTPS traffic.

File and Directory Structure¶

The application utilizes the following directory structure on the host server:

/root/linuxpatch: The primary installation directory containing the application source code, configuration scripts, and Docker Compose files.
/root/linuxpatch/data: The persistent data directory mounted to the application container.
/root/linuxpatch/data/.env: The environment configuration file containing database credentials, session secrets, and SMTP settings.
/root/linuxpatch/data/certs: Directory for storing SSL/TLS certificates.
/root/linuxpatch/data/logs: Directory for storing application logs.
/data/nginx/user_conf.d: Host directory for Nginx user configurations, mounted into the proxy container.

Application Installation Process¶

The LinuxPatch Appliance is deployed using a Docker Compose configuration. The installation involves cloning the repository and executing a configuration script that generates necessary credentials and updates the Docker Compose file.

Create the installation directory:
```
mkdir -p /root/linuxpatch
```

Clone the LinuxPatch repository:

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

Create the required Docker volume for Nginx secrets:
```
docker volume create nginx_secrets
```
Navigate to the installation directory:
```
cd /root/linuxpatch
```
Execute the configuration script to generate the .env file and update docker-compose.yml:
```
chmod +x configure.sh
./configure.sh
```

The configure.sh script performs the following actions: - Creates data/certs and data/logs directories. - Generates random credentials for the database, SMTP, and admin user. - Writes these credentials to data/.env. - Updates docker-compose.yml with the generated environment variables. - Starts the services using docker compose up -d.

Docker Containers and Their Deployment¶

The application consists of four main containers defined in docker-compose.yml:

nginx:
Image: jonasal/nginx-certbot:latest
Function: Acts as a reverse proxy and handles SSL certificate management via Certbot.
Ports: Exposes 80 and 443 on the host.
Volumes: Mounts nginx_secrets for Let's Encrypt certificates and /data/nginx/user_conf.d for custom Nginx configurations.
linuxpatch-app:
Image: linuxpatch/appliance:latest
Function: The main application container.
Command: ./web
Dependencies: Waits for linuxpatch-db and linuxpatch-redis to be healthy before starting.
Volumes: Mounts ./data to /app/data for persistent configuration and logs.
linuxpatch-db:
Image: percona/percona-server:8.0
Function: MySQL database server.
Command: mysqld
Volumes: Mounts linuxpatch-mysql-data to /var/lib/mysql.
Healthcheck: Uses mysqladmin ping to verify service status.
linuxpatch-redis:
Image: redis:6
Function: In-memory data store for caching and session management.
Command: redis-server
Volumes: Mounts linuxpatch-redis-data to /data.
Healthcheck: Uses redis-cli ping to verify service status.

The containers communicate over a dedicated Docker bridge network named linuxpatch-app-network.

Databases¶

The application uses two database services:

MySQL (Percona Server):
Hostname within Docker network: linuxpatch-db
Port: 3306
Database Name: Defined in data/.env as DB_NAME (default: linuxpatch).
Username: Defined in data/.env as DB_USERNAME.
Password: Defined in data/.env as DB_PASSWORD.
Storage: Data is persisted in the linuxpatch-mysql-data Docker volume.
Redis:
Hostname within Docker network: linuxpatch-redis
Port: 6379
Database Index: Defined in data/.env as REDIS_DATABASE (default: 0).
Storage: Data is persisted in the linuxpatch-redis-data Docker volume.

All database credentials and connection parameters are stored in the data/.env file and passed to the linuxpatch-app container as environment variables.

Proxy Servers¶

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

Image: jonasal/nginx-certbot:latest
Function: Handles incoming HTTP and HTTPS traffic, manages SSL certificates via Certbot, and proxies requests to the linuxpatch-app container.
Configuration:
The proxy_pass directive is configured to forward traffic to http://linuxpatch-app.
Custom Nginx configurations are stored in /data/nginx/user_conf.d on the host and mounted into the container.
SSL/TLS:
Certificates are stored in the nginx_secrets volume at /etc/letsencrypt.
The application container expects certificates at /app/data/certs/server.crt, /app/data/certs/server.key, and /app/data/certs/ca.crt.
Ports:
Port 80: HTTP traffic.
Port 443: HTTPS traffic.

Permission Settings¶

The deployment script sets specific permissions for directories and files:

/root/linuxpatch: Created with 0644 permissions, owned by root:root.
configure.sh: Executable permissions (0744) are set to allow script execution.
docker-compose.yml: Created with 0644 permissions, owned by root:root.
data/certs and data/logs: Created with 755 permissions to allow read and execute access for the application processes.

The Docker containers run with the necessary internal permissions to access mounted volumes and execute commands.

Starting, Stopping, and Updating¶

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

Start Services:
```
docker compose up -d
```
Stop Services:
```
docker compose down
```
Restart Services:
```
docker compose restart
```
Update Application Image: The linuxpatch-app service is configured with pull_policy: always, ensuring the latest image is pulled before starting. To update the application:
```
docker compose pull linuxpatch-app
docker compose up -d linuxpatch-app
```
View Logs:
```
docker compose logs -f
```
Check Service Status:
```
docker compose ps
```

The configure.sh script automatically starts the services upon successful configuration. Subsequent changes to the docker-compose.yml or .env file require a restart of the services to take effect.