Deployment Overview of Gitea on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Linux server running Ubuntu with root privileges. The system must have Docker and Docker Compose installed to manage the containerized application. The following ports must be available and open on the server firewall:

• Port 3000 for the Gitea web interface.
• Port 22 for SSH access to the Gitea instance.
• Ports 80 and 443 for the Nginx reverse proxy and SSL termination.

A valid domain name is required to configure the Nginx proxy and obtain SSL certificates via Certbot.

File and Directory Structure¶

The application and its supporting services utilize the following directory structure on the host system:

• /opt/gitea: Contains the Docker Compose configuration file for the Gitea service.
• /data/gitea: The primary data directory for Gitea, storing repositories, configuration files, and logs.
• /root/nginx: Contains the Docker Compose configuration for the Nginx proxy and Certbot.
• /data/nginx/user_conf.d: Stores custom Nginx configuration files for specific host keys.
• /data/nginx/nginx-certbot.env: Environment file containing configuration for the Certbot service.
• /etc/timezone and /etc/localtime: System files configured to Europe/Moscow for consistent timekeeping.

Application Installation Process¶

The Gitea application is deployed using Docker Compose. The installation process involves creating the necessary directories and generating the docker-compose.yml file within /opt/gitea. The configuration specifies the following:

• Image: gitea/gitea with a specific version tag.
• Container Name: gitea.
• Environment Variables:
• USER_UID=1000
• USER_GID=1000
• Restart Policy: always.
• Network: A dedicated internal network named gitea.
• Volume Mounts:
• The host directory {{ gitea_data_dir }} is mounted to /data inside the container.
• Host timezone files are mounted read-only to /etc/timezone and /etc/localtime.
• Port Mapping:
• Host port {{ gitea_port }} maps to container port 3000.
• Host port {{ gitea_ssh_port }} maps to container port 22.

The timezone is explicitly set to Europe/Moscow by copying the timezone file and creating a symbolic link for the local time.

Docker Containers and Their Deployment¶

Two primary Docker Compose setups are utilized for the deployment:

1. Gitea Service: The Gitea container is managed via the docker-compose.yml file located in /opt/gitea. The service is started using the command docker-compose up -d executed from the /opt/gitea directory. The container is configured to restart automatically upon failure or system reboot.

2. Nginx and Certbot Service: A separate Docker Compose configuration is generated and stored in /root/nginx/compose.yml. This setup includes:

   • Image: jonasal/nginx-certbot:latest.
   • Restart Policy: unless-stopped.
   • Network Mode: host.
   • Volumes:
   • nginx_secrets (external volume) mounted to /etc/letsencrypt.
   • /data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d.
   • Environment: Configured via /data/nginx/nginx-certbot.env and includes the email [email protected] for certificate notifications.

The Nginx service is started using docker compose up -d from the /root/nginx directory.

Proxy Servers¶

The deployment utilizes an Nginx reverse proxy container to handle incoming traffic and SSL termination. The proxy configuration is managed through the nginx-certbot image.

• Configuration Location: Custom host configurations are stored in /data/nginx/user_conf.d.
• Proxy Pass: The Nginx configuration is updated to forward requests to the Gitea container running on the host. The specific directive added is:

  proxy_pass http://127.0.0.1:3000;
  

  This line is inserted into the location / block of the configuration file named {{ prefix }}{{ server_id }}.hostkey.in.conf.
• SSL Certificates: Managed automatically by the Certbot component within the Nginx container, storing secrets in the nginx_secrets volume.

Permission Settings¶

File and directory permissions are set as follows to ensure proper operation and security:

• /opt/gitea: Owned by root:root with mode 0755.
• {{ gitea_data_dir }}: Owned by {{ gitea_user }}:{{ gitea_user }} with mode 0755.
• /root/nginx: Owned by root:root with mode 0755.
• /root/nginx/compose.yml: Owned by root:root with mode 0644.
• /data/nginx/user_conf.d: Accessible by the Nginx container for reading configuration files.

Starting, Stopping, and Updating¶

The services are managed using Docker Compose commands executed from their respective configuration directories.

• Starting Gitea: Execute the following command from the /opt/gitea directory:

  docker-compose up -d
  

• Starting Nginx Proxy: Execute the following command from the /root/nginx directory:

  docker compose up -d
  

• Ensuring Service Status: The Gitea container is configured with a restart policy of always, ensuring it remains running. The Nginx container uses a restart policy of unless-stopped.

• Updating: To update the application, the docker-compose.yml file must be modified with the new image version, followed by re-running the docker-compose up -d command. The Nginx configuration updates involve regenerating the compose.yml file and restarting the service.