Deployment Overview of Jenkins on Server¶

Prerequisites and Basic Requirements¶

The deployment of Jenkins on the server requires the following system specifications and privileges:

Operating System: Ubuntu (compatible with apt package manager).
Privileges: Root access or sudo privileges are required to install system packages, manage services, and configure Docker.
Domain: The application is configured to operate under the hostkey.in zone.
Ports:
Internal application port: 8080.
External secure port: 443.

FQDN of the Final Panel¶

The application is accessible via the Fully Qualified Domain Name (FQDN) constructed using the prefix jenkins-marketplace-app and the specific Server ID. The format is:

jenkins-marketplace-app<Server ID>.hostkey.in:443

Replace <Server ID> with the actual identifier assigned to the server instance.

File and Directory Structure¶

The deployment utilizes the following directory structure for configuration, data, and certificates:

/root/nginx: Directory containing the Docker Compose configuration for the proxy.
/root/nginx/compose.yml: Docker Compose file defining the Nginx and Certbot services.
/data/nginx/user_conf.d: Directory storing custom Nginx configuration files for the application.
/data/nginx/user_conf.d/jenkins-marketplace-app<Server ID>.hostkey.in.conf: Specific Nginx configuration file for the Jenkins instance.
/data/nginx/nginx-certbot.env: Environment file for the Nginx-Certbot container.
/etc/default/jenkins: System configuration file for the Jenkins service.
/usr/share/keyrings/jenkins-keyring.asc: GPG key for the Jenkins repository.
/etc/letsencrypt: Volume mount point for SSL certificates managed by the proxy container.

Application Installation Process¶

The Jenkins application is installed as a native system service using the official Jenkins repository. The process includes the following steps:

System Preparation: The package index is updated, and required dependencies such as fontconfig and openjdk-21-jre-headless are installed.
Repository Configuration: The Jenkins GPG key is downloaded and added to the system keyring. The official Jenkins Debian repository is added to the APT sources.
Package Installation: The jenkins package is installed via the apt package manager.
Java Configuration: The JAVA_HOME variable is detected from the installed OpenJDK 21 JRE and explicitly set in the /etc/default/jenkins file to ensure the service uses the correct Java runtime.
Service Activation: The Jenkins service is enabled to start on boot and started immediately.

Docker Containers and Their Deployment¶

A reverse proxy and SSL termination layer is deployed using Docker. The deployment utilizes a docker compose file located at /root/nginx/compose.yml.

The container configuration includes:

Image: jonasal/nginx-certbot:latest.
Restart Policy: unless-stopped.
Network Mode: host.
Environment Variables:
CERTBOT_EMAIL: Set to [email protected].
Volumes:
nginx_secrets: Mounted to /etc/letsencrypt for SSL certificate storage.
/data/nginx/user_conf.d: Mounted to /etc/nginx/user_conf.d to provide custom Nginx configurations.

The container is started using the command:

docker compose up -d

executed from the /root/nginx directory.

Proxy Servers¶

The application is fronted by an Nginx container running with Certbot for SSL management.

Proxy Configuration: The Nginx configuration file for the application is located at /data/nginx/user_conf.d/jenkins-marketplace-app<Server ID>.hostkey.in.conf.
Routing: The proxy is configured to forward requests from the root path (/) to the internal Jenkins instance.
Backend Target: The proxy passes traffic to http://127.0.0.1:8080.
SSL/TLS: SSL certificates are automatically managed by the nginx-certbot container using the letsencrypt volume.

Permission Settings¶

The following permission settings are applied to critical directories and files:

/root/nginx: Owned by root:root with mode 0755.
/root/nginx/compose.yml: Owned by root:root with mode 0644.
/usr/share/keyrings/jenkins-keyring.asc: Mode 0644.
/etc/default/jenkins: Modified by the installation process to set JAVA_HOME.

Location of Configuration Files and Data¶

Key configuration files and data locations are summarized below:

File or Directory	Path	Description
Docker Compose	`/root/nginx/compose.yml`	Defines the Nginx and Certbot container.
Nginx Config	`/data/nginx/user_conf.d/jenkins-marketplace-app<Server ID>.hostkey.in.conf`	Custom proxy rules for Jenkins.
Nginx Env	`/data/nginx/nginx-certbot.env`	Environment variables for the proxy container.
Jenkins Config	`/etc/default/jenkins`	System service configuration including `JAVA_HOME`.
SSL Certificates	`/etc/letsencrypt`	Volume mount for SSL certificates.
GPG Key	`/usr/share/keyrings/jenkins-keyring.asc`	Repository signing key.

Available Ports for Connection¶

The application exposes the following ports:

Port 443: HTTPS traffic handled by the Nginx proxy container. This is the primary entry point for external users.
Port 8080: Internal HTTP traffic used by the Jenkins application. This port is bound to 127.0.0.1 and is only accessible locally by the proxy.

Starting, Stopping, and Updating¶

The Jenkins application is managed as a native systemd service, while the proxy is managed via Docker Compose.

Jenkins Service Management:

Start the service:
```
systemctl start jenkins
```
Stop the service:
```
systemctl stop jenkins
```
Restart the service:
```
systemctl restart jenkins
```
Check service status:
```
systemctl status jenkins
```
Enable service on boot:
```
systemctl enable jenkins
```

Proxy Container Management:

Start or restart the proxy stack:
```
cd /root/nginx
docker compose up -d
```
Stop the proxy stack:
```
cd /root/nginx
docker compose down
```