Gitea is an open-source code-hosting solution based on the Git platform. It offers a range of features such as repository file editing, issue tracking, pull requests, user management, notifications, built-in wiki, and more. In this tutorial, we will guide you through the process of installing and configuring Gitea on a Debian 12 server using Docker.

Before we begin, please ensure that you have the following prerequisites:

• A server running Debian 12.
• A non-root user with sudo privileges.
• A Fully Qualified Domain Name (FQDN) pointing to your server.
• Swap storage enabled if you have 1GB RAM.
• All packages on your server are up to date.

Let’s get started with the installation process.

Step 1: Configure Firewall

The first step is to configure the firewall on your Debian 12 server. By default, Debian comes with ufw (Uncomplicated Firewall). You can check if the firewall is running by running the following command:

sudo ufw status

If the firewall is not active, you can enable it by running the following commands:

sudo ufw allow OpenSSH
sudo ufw allow http
sudo ufw allow https
sudo ufw enable

Make sure to allow SSH, HTTP, and HTTPS ports to ensure smooth communication with your server.

Step 2: Install Docker and Docker Compose

Debian 12 ships with an older version of Docker. To install the latest version, you need to import the Docker GPG key and create a Docker repository file. Here are the steps to follow:

1. Import the Docker GPG key:

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker.gpg

2. Create a Docker repository file:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3. Update the system repository list:

sudo apt update

4. Install Docker and Docker Compose:

sudo apt install docker-ce docker-ce-cli containerd.io docker-compose

5. Verify that Docker is running:

sudo systemctl status docker

6. Add your user to the Docker group:

sudo usermod -aG docker$(whoami)

Remember to log out and log back in or use the following command to activate the changes:

su - ${USER}

Step 3: Create a Git User

To ensure secure SSH access to your Gitea installation, it is recommended to create a separate git user on your server. Here’s how you can create the user:

1. Run the following command to create the git user:

sudo adduser --system --shell/bin/bash --gecos 'Git Version Control' --group --disabled-password --home/home/git git

2. Take note of the values for UID and GID, which will be required in the next step.

Step 4: Configure and Install Gitea

Now, let’s configure and install Gitea using Docker.

1. Check your system’s current timezone by running the following command:

timedatectl

If you need to change the timezone, you can use the following command:

sudo timedatectl set-timezone <timezone>

2. Create the necessary directories for Gitea:

mkdir ~/gitea-docker
cd ~/gitea-docker
mkdir {gitea,postgres}

3. Create a Docker Compose file for Gitea:

nano docker-compose.yml

Paste the following code into the file:

services:
server:
image: gitea/gitea:1.21.0
container_name: gitea
environment:
- USER_UID=105
- USER_GID=111
- GITEA__database__DB_TYPE=postgres
- GITEA__database__HOST=db:5432
- GITEA__database__NAME=gitea
- GITEA__database__USER=gitea
- GITEA__database__PASSWD=gitea
restart: always
volumes:
- ./gitea:/data
- /home/git/.ssh/:/data/git/.ssh
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2221:22"
depends_on:
- db

db:
image: postgres:15
restart: always
environment:
- POSTGRES_USER=gitea
- POSTGRES_PASSWORD=gitea
- POSTGRES_DB=gitea
volumes:
- ./postgres:/var/lib/postgresql/data

networks:
gitea:
external: false

Save the file and exit the editor.

4. Customize your Gitea installation (optional): You can customize your Gitea installation by adding an app.ini file to the ~/gitea-docker/gitea/gitea/conf directory. This can be done after the installation is complete.
5. Install Gitea using Docker Compose:

docker-compose up- d

6. Check the status of the containers:

docker ps

Congratulations! You have successfully installed and configured Gitea using Docker on your Debian 12 server.

To access your Gitea instance, you can visit the URL https://gitea.example.com in your web browser. Replace gitea.example.com with your own domain name. You will be redirected to the Gitea installation page, where you can set up your administrator account and configure other settings.

Step 5: Install Nginx

To enhance the security and performance of your Gitea installation, it is recommended to use Nginx as a reverse proxy. Here’s how you can install Nginx on your Debian 12 server:

1. Import the Nginx signing key:

curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg > /dev/null

2. Add the Nginx repository:

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/debian $(lsb_release -cs) nginx" | sudo tee /etc/apt/sources.list.d/nginx.list

3. Update the system repositories:

sudo apt update

4. Install Nginx:

sudo apt install nginx

5. Start the Nginx server:

sudo systemctl start nginx

6. Verify the installation:

sudo systemctl status nginx

Nginx is now installed on your server and running as a reverse proxy for your Gitea instance.

Step 6: Install SSL

To secure the communication between your server and clients, it is recommended to install an SSL certificate. We will be using Certbot to generate and install the SSL certificate. Here’s how you can install Certbot and generate the certificate:

1. Install Snapd package:

sudo apt install snapd

2. Update Snapd to the latest version:

sudo snap install core && sudo snap refresh core

3. Install Certbot:

sudo snap install --classic certbot

4. Create a symbolic link for Certbot:

sudo ln -s /snap/bin/certbot /usr/bin/certbot

5. Verify that Certbot is functioning correctly:

certbot --version

6. Generate the SSL certificate:

sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m test@example.com -d gitea.example.com

Make sure to replace gitea.example.com with your own domain name.

Congratulations! You have successfully installed an SSL certificate for your Gitea installation.

Step 7: Configure Nginx

Now, let’s configure Nginx to work as a reverse proxy for your Gitea instance.

1. Create a configuration file for your site:

sudo nano /etc/nginx/conf.d/gitea.conf

2. Paste the following code into the file:

# Connection header for WebSocket reverse proxy
map $http_upgrade $connection_upgrade {
default upgrade;
"" close;
}

map $remote_addr $proxy_forwarded_elem {
# IPv4 addresses can be sent as-is
~^[0-9.]+$ "for=$remote_addr";
# IPv6 addresses need to be bracketed and quoted
~^[0-9A-Fa-f:.]+$ "for=\"[$remote_addr]\"";
# Unix domain socket names cannot be represented in RFC 7239 syntax
default "for=unknown";
}

map $http_forwarded $proxy_add_forwarded {
# If the incoming Forwarded header is syntactically valid, append to it
"~^(,[ \t]*)*([!#$%&'*+.^_`|~0-9A-Za-z-]+=([!#$%&'*+.^_`|~0-9A-Za-z-]+|\"([\\\t \\\x21-\\\x5B\\\x5D-\\\x7E\\\x80-\\\xFF]|\\\\[\\\t \\\x21-\\\x7E\\\x80-\\\xFF])*\"))?(;([!#$%&'*+.^_`|~0-9A-Za-z-]+=([!#$%&'*+.^_`|~0-9A-Za-z-]+|\"([\\\t \\\x21-\\\x5B\\\x5D-\\\x7E\\\x80-\\\xFF]|\\\\[\\\t \\\x21-\\\x7E\\\x80-\\\xFF])*\"))?)*([ \t]*,([ \t]*([!#$%&'*+.^_`|~0-9A-Za-z-]+=([!#$%&'*+.^_`|~0-9A-Za-z-]+|\"([\\\t \\\x21-\\\x5B\\\x5D-\\\x7E\\\x80-\\\xFF]|\\\\[\\\t \\\x21-\\\x7E\\\x80-\\\xFF])*\"))?(;([!#$%&'*+.^_`|~0-9A-Za-z-]+=([!#$%&'*+.^_`|~0-9A-Za-z-]+|\"([\\\t \\\x21-\\\x5B\\\x5D-\\\x7E\\\x80-\\\xFF]|\\\\[\\\t \\\x21-\\\x7E\\\x80-\\\xFF])*\"))?)*)?)*$" "$http_forwarded, $proxy_forwarded_elem";
# Otherwise, replace it
default "$proxy_forwarded_elem";
}

# Redirect all non-encrypted to encrypted
server {
listen 80;
listen [::]:80;
server_name gitea.example.com;
return 301 https://$host$request_uri;
}

server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name gitea.example.com;

ssl_certificate /etc/letsencrypt/live/gitea.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/gitea.example.com/privkey.pem;
ssl_trusted_certificate /etc/letsencrypt/live/gitea.example.com/chain.pem;

ssl_session_timeout 1d;
ssl_session_cache shared:MozSSL:10m;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
ssl_dhparam /etc/ssl/certs/dhparam.pem;

resolver 1.1.1.1 1.0.0.1 [2606:4700:4700::1111] [2606:4700:4700::1001] 8.8.8.8 8.8.4.4 [2001:4860:4860::8888] [2001:4860:4860::8844] valid=60s;
resolver_timeout 2s;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

access_log /var/log/nginx/gitea.access.log main;
error_log /var/log/nginx/gitea.error.log;

tcp_nopush on;

# security headers
add_header X-XSS-Protection "1; mode=block" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Content-Security-Policy "default-src 'self' http: https: ws: wss: data: blob: 'unsafe-inline'; frame-ancestors 'self';" always;
add_header Permissions-Policy "interest-cohort=()" always;

# . files
location ~ /\. {
deny all;
}

location / {
client_max_body_size 100M;
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_cache_bypass $http_upgrade;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header Forwarded $proxy_add_forwarded;
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
}

7. Test the Nginx configuration:

sudo nginx -t

If the configuration is correct, you should see a successful message.

8. Reload the Nginx service:

sudo systemctl reload nginx

Congratulations! You have successfully configured Nginx as a reverse proxy for your Gitea installation.

Step 8: Access and Set up Gitea

Now that your Gitea installation is up and running, you can access it through your domain name. Open your web browser and visit https://gitea.example.com (replace gitea.example.com with your own domain name).

You will be redirected to the Gitea installation page, where you can set up your administrator account and configure other settings. Follow the on-screen instructions to complete the setup.

Step 9: Create First Repository

Once you have set up your administrator account, you can create your first repository. To do this, follow these steps:

1. Log in to your Gitea instance using your administrator credentials.
2. Click the “+” sign on the dashboard to create a new repository.
3. Enter the repository details, including the repository name, default issue label, and license.
4. Select the default branch for your repository.
5. Click the “Create repository” button to create your first repository.

Congratulations! You have successfully created your first repository on Gitea.

Step 10: Set up SSH

To use SSH with your Gitea repository, you need to set up SSH keys. Here’s how you can set up SSH on your Gitea instance:

1. Generate a new SSH key on your local machine:

ssh-keygen -f ~/.ssh/gitea-demo -t rsa -b 4096 -C "ShapeHost Gitea Demo" -q -N "yourpassphrase"

Replace yourpassphrase with a strong passphrase.

2. Open your Gitea profile settings and switch to the SSH/GPG Keys tab.
3. Add a name for your SSH key, and copy the public key content from ~/.ssh/gitea-demo.pub.
4. Click the “Add Key” button to add the SSH key to your Gitea instance.
5. Configure your SSH agent on your local machine:

eval $(ssh-agent-t3600)

6. Add the SSH key to the SSH agent:

ssh-add ~/.ssh/gitea-demo

Enter your passphrase when prompted.

Congratulations! You have successfully set up SSH for your Gitea repository.

Step 11: Clone Repository using SSH

To clone your Gitea repository using SSH, follow these steps:

1. Visit your repository page on Gitea and copy the SSH URL.
2. On your local machine, open a terminal and run the following command to clone the repository:

git clone ssh://test@example.com:2221/shapehost/shapehost.git

Replace shapehost with your username, and shapehost with the name of your repository.

Congratulations! You have successfully cloned your Gitea repository using SSH.

Step 12: Testing First Commit

Now that you have cloned your repository, you can make changes and commit them back to the repository. Here’s how you can test your first commit:

1. Open the README.md file in your cloned repository.
2. Make some changes to the file.
3. Save the file and exit the editor.
4. Check the git status:

git status

5. Add the modified file for commit:

git addREADME.md

6. Commit the changes:

git commit -m "Update the Readme file for Gitea tutorial."

7. Push the changes to your Gitea repository:

git push origin main

Congratulations! You have successfully made your first commit to your Gitea repository.

Step 13: Backup and Restore Gitea

To ensure the safety of your Gitea data, it is essential to perform regular backups. Here’s how you can backup and restore Gitea:

Backup Gitea:

1. Run the following command to back up your Gitea data:

docker exec -u git -it -w /app/gitea gitea bash -c '/usr/local/bin/gitea dump -c /data/gitea/conf/app.ini'

2. The backup file will be created in the /app/gitea/gitea-dump-<timestamp>.zip location inside the Docker container.

Restore Gitea:

1. Shut down and remove the existing Gitea containers.
2. Extract the backup file:

unzip gitea-dump-<timestamp>.zip

3. Move the data and repository files to the correct locations:

mv data/* /data/gitea
mv repos/* /data/git/gitea-repositories/

4. Fix file permissions:

chown -R git:git/data

5. Regenerate Git Hooks:

/usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks

Congratulations! You have successfully backed up and restored your Gitea installation.

Conclusion

In this tutorial, we have covered the installation and configuration of Gitea on a Debian 12 server using Docker. We have also set up Nginx as a reverse proxy and secured the communication with an SSL certificate. Additionally, we have explored the process of creating repositories, setting up SSH, and performing the first commit. Lastly, we have discussed the importance of backups and how to restore a Gitea installation.

Gitea is a powerful tool for code hosting and collaboration, offering a wide range of features to streamline your development workflow. By following this guide, you can harness the full potential of Gitea in a secure and efficient manner.

If you are looking for reliable cloud hosting services, consider Shape.host. They provide Cloud VPS solutions that are scalable, secure, and tailored to meet your specific requirements. Shape.host offers top-notch support and ensures the highest level of performance for your applications. Visit Shape.host for more information and explore their hosting options.