Gitea is a lightweight, open source and self-hosted code hosting solution, similar to GitHub, Gitlab and BitBucket. It is mainly written in Go and can run on Windows, Linux, macOS, ARM, etc. Gitea was developed as a fork of Gogs and published under the MIT license.
Gitea is easy to install and offers several options for installation. You can install Gitea with the binary for your platform and architecture, install and ship it as a container with Docker, or install it as a package (.deb, .rpm). Gitea has minimal system requirements and can be installed on a machine with 2CPU cores and 1GB RAM, typically for small projects/teams. It is a lightweight, feature-rich and self-hosted alternative to services like GitHub.
In this guide, you will set up Gitea as a container with Docker on the Debian 11. Then you will use Apache as a reverse proxy for gitea, secure the use of gitea with SSL Letsencrypt and set up a project/repository with gitea.
Requirements
- A Debian server - assuming you are using a new Debian server installation.
- A root user or a user with root privileges - to install new packages and make system-wide changes.
Installing Docker CE under Debian
By default, the Debian repository provides packages for Docker. In this tutorial, however, you will install Docker from the official Docker repository. Therefore, you will first add the Docker repository and the gpg key to your Debian system.
Using the Docker packages from the official Docker repository ensures that you get the latest version with newer features of Docker.
1. before adding the Docker repository, run the following command to install the package dependencies
sudo apt install \ apt-transport-https \ ca-certificates \ curl \ gnupg \ lsb-release
2. once the installation is complete, add the Docker repository for the Debian system and add the Docker gpg key with the following command
echo \ "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
3. now update your Debian repositories. Then install Docker CE with the following command.
apt update apt install docker-ce docker-ce-cli containerd.io
Type"y" and press"Enter" to confirm and continue the installation of the packages.
Once the installation is complete, the Docker service is automatically active and running on your Debian system. It will also run automatically when booting/starting the system.
Installation of Docker Compose
Compose is a command line tool for creating and managing Docker applications with multiple containers. You can simply define all containers of your application in a single YAML configuration "docker-compose.yml" and then deploy and start your application with the docker-compose command.
Compose comes with a single binary package. You can install it by downloading the binary and placing it in the "bin" directory on your system.
1. download the Compose binary to the "/usr/local/bin" directory using the following command
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
2. then execute the chmod command to convert the file into an executable program.
sudo chmod +x /usr/local/bin/docker-compose
3. now run the command 'docker-compose' to verify the installation.
docker-compose --version
You will see similar output as below.
Add a new system user for Gitea
For security reasons, it is always advisable to run Docker container applications with non-root users. In this tutorial, you will create a new user "gitea" under which all containerized applications will run.
1. to create a new user on the Linux system, execute the following command.
useradd -m -s /bin/bash gitea passwd gitea
Enter a new password for the user "gitea" and repeat it.
2. to enable the user "gitea" to run Docker containers, you must add the user "gitea" to the "docker" group with the following usermod command.
usermod -aG docker gitea
3. then log in with the user "gitea" and start the container "hello-world" with the following command.
su - gitea docker run hello-world
If your configuration is correct, you will see an output similar to the one below.
Setting up the Gitea installation environment
Gitea provides a ready-made Docker image for its installation. Gitea supports MySQL and PostgreSQL databases. In this tutorial, you will create a docker-compose YAML configuration for the Gitea installation environment. It includes certain networks, the gitea service and the PostgreSQL database.
1. log in as user "gitea", create the project directory"gitea" and change your working directory to it
su - gitea mkdir -p gitea; cd gitea/
2. create the script "docker-compose.yml" with nano edit.
nano docker-compose.yml
First copy the following line and paste it at the beginning of the line. This is an indication that you are using the docker-compose version 3 script.
version: "3"
Define the specific network name"gitea" for your installation environment.
networks: gitea: external: false
Define the configuration of the services. All services of your application stack must be in the parent section of the service configuration.
services:
Define the services gitea with the following information:
- The service name is " server" and the container is"gitea".
- Use the base image gitea latest version.
- Make sure that the database name, user and password match the database service.
- Specify the network with"gitea".
- The app volume directory is available under '/installation/path/gitea'.
- Assign the TCP port"3000" for the Gitea application and the port"22" for the SSH Git support. Also make sure that the SSH service on the host machine uses a different port.
- This service is executed after the database service.
server: image: gitea/gitea:latest container_name: gitea environment: - USER_UID=1000 - USER_GID=1000 - GITEA__database__DB_TYPE=postgres - GITEA__database__HOST=db:5432 - GITEA__database__NAME=gitea - GITEA__database__USER=gitea - GITEA__database__PASSWD=gitea restart: always networks: - gitea volumes: - ./gitea:/data - /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro ports: - "3000:3000" - "22:22" depends_on: - db
Now define the database service with the following details:
- The database service is given the name"db".
- Using the PostgreSQL 13 base image
- Define the database name and the user for the Gitea application.
- Use the same and specific network"gitea".
- The data directory for the db service is available under '/installation/dir/postgres'.
db: image: postgres:13 restart: always environment: - POSTGRES_USER=gitea - POSTGRES_PASSWORD=gitea - POSTGRES_DB=gitea networks: - gitea volumes: - ./postgres:/var/lib/postgresql/data
Save the configuration by pressing'Ctrl+x', typing'y' and then pressing'Enter' to exit.
Below you can see the finished configuration that you will use.
version: "3" networks: gitea: external: false services: server: image: gitea/gitea:latest container_name: gitea environment: - USER_UID=1000 - USER_GID=1000 - GITEA__database__DB_TYPE=postgres - GITEA__database__HOST=db:5432 - GITEA__database__NAME=gitea - GITEA__database__USER=gitea - GITEA__database__PASSWD=gitea restart: always networks: - gitea volumes: - ./gitea:/data - /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro ports: - "3000:3000" - "22:22" depends_on: - db db: image: postgres:13 restart: always environment: - POSTGRES_USER=gitea - POSTGRES_PASSWORD=gitea - POSTGRES_DB=gitea networks: - gitea volumes: - ./postgres:/var/lib/postgresql/data
3. to create and start the Gitea Docker services, run the docker-compose command.
docker-compose up -d
4. when all processes are completed, check your gitea docker installation with the following command.
docker-compose ps
If your installation is correct, you will see two container services: "gitea" as an application and"gitea_db_1" as a database service. Both container services are in"Up" status, i.e. they are running.
5. you can also check the logs of your Gitea application with the following docker-compose command.
docker-compose logs
You will see that a lot of log messages are generated during the initialization of the container services.
Set up Apache as a reverse proxy for Gitea
In this step, you will install and configure the Apache web server as a reverse proxy for the Gitea docker service. You will also secure your Gitea installation with SSL from Letsencrypt.
1. run the following command to install the apache2, certbot and certbot-plugin packages for apache.
apt install apache2 certbot python3-certbot-apache
Type"y" and press"Enter" to confirm and continue the installation.
2. when the installation is complete, change the working directory to"/etc/apache/sites-available" and create a new virtual Apache configuration"gitea.conf" with nano.
cd /etc/apache2/sites-available/ nano gitea.conf
Copy and paste the following configuration. Make sure that you replace the domain name with your own.
# apache2 port 80 <VirtualHost *:80> ServerName git.example.io ErrorLog /var/log/apache2/git.example.io-error.log CustomLog /var/log/apache2/git.example.io-access.log combined
ProxyPreserveHost On
ProxyRequests off
AllowEncodedSlashes NoDecode
ProxyPass / http://localhost:3000/ nocanon
ProxyPassReverse / http://localhost:3000/
</VirtualHost>
Press the key combination"Ctrl+x", enter"y" and then press"Enter" to save and exit.
Then execute the following command to activate the configuration of the virtual host"gitea.conf". 3.
a2ensite gitea.conf
3. now activate some Apache modules and check your Apache2 configuration with the command below.
a2enmod ssl proxy proxy_http apachectl configtest
If you have no errors, restart the apache2 service to apply the new configuration.
systemctl restart apache2
4. next, generate SSL Letsencrypt with the certbot command below.
certbot --apache --agree-tos -m [email protected] -d git.example.io
You will be asked a few questions.
- An e-mail address: When the SSL certificate expires, you will be directed to this email.
- Letsencrypt TOS (Terms of Service): Enter "A " to agree.
- Share email with the EFF: You can select"N" for no.
- Automatically redirect HTTP to HTTPS: Select the number "2" to enable automatic redirection.
Once the process is complete, you will see that the SSL certificates are available in the "/etc/letsencrypt/live/git.example.io" directory. Also, the configuration of your Apache2 virtual host has changed due to the additional configuration of letsencrypt.
5. to make sure that the new Apache configuration has been applied, restart the apache2 service and check it with the following command.
systemctl restart apache2
systemctl is-enabled apache2
systemctl status apache2
You will get a similar output as below.
The apache service is enabled and will be started automatically at system startup. The apache2 service is"active (running)" as a reverse proxy for the Gitea Docker service. And it runs with activated SSL from Letsencrypt.
Setting up Gitea for the first time
At this stage, you have completed the installation of Gitea. Now set up your Gitea application data and create a new administrator user.
Open your web browser and go to the domain of the Gitea installation.
1. in the "General settings" section, you must make the most important configurations as follows
- Website title: Gitea: Git with a cup of tea
- SSH server domain: git.example.io (this activates SSH support)
- SSH server port: 22
- Gitea base URL: https://git.example.io
2. go to the"Optional settings" and click on the additional option"Administrator account settings".
Create a new administrator user for Gitea:
- Administrator Username: johndoe
- Password: johndoe ********
- Confirm the password: ********
- E-mail address: [email protected]
Now click on the"Install Gitea" button to start your Gitea installation.
3. if the installation is correct, you will be redirected to the Gitea home page (see below).
Common problem:
If you are redirected to the address "http://localhost:3000", you need to set up your"Gitea Base URL" domain name correctly. Make sure the value for"Gitea Base URL" matches the domain name you are using for the Gitea installation.
Check the Gitea installation: Create first repository
On the Gitea standard user page, you will see the sections "Repository" and"Organization".
1. go to the "Repository" section and click on the"+" button to create a new repository.
Enter the repository configuration details as follows.
- Repository name: dotfiles
- Visibility: Mark as check for private repository
- Description: Enter your description
Scroll to the bottom and click on the"Create" button.
You have successfully created a new repository on Gitea.
2. to set up the git repository on your local computer, you must have the git package installed on your system.
Set the global username and email address for your git repository by executing the following command.
git config --global user.email "[email protected]" git config --global user.name "johndoe"
3. create a new directory "dotfiles", change the current working directory to it and create and edit the new file "README.md".
Execute the following command.
mkdir dotfiles; cd dotfiles
touch README.md
nano README.md
Now initialize the new Git repository with the Git command below.
git init
The new Git repository has been initialized.
4. add the changes of the file"README.md" to the current Git repository and commit them.
git add README.md git commit -m "first commit - add README.md"
Add the remote repository to your gitea repository and push all files there.
git remote add origin https://git.example.io/johndoe/dotfiles.git git push -u origin master
Enter your gitea username and password. In this example, use the username "johndoe". When your push process is complete, you will see an output similar to the one below.
4. to check your first commit to the Gitea repository, go to your repository with the web browser. You will see that your code is available in the Gitea repository.
Below you can see a screenshot after adding new code to the "dotfiles" repository.
Conclusion
Congratulations! You have learned how to install Gitea with the PostgreSQL database and the Apache repository using the Docker container on the latest Debian 11 server. You also secured your Gitea deployment with SSL from Letsencrypt. You also created a new private repository on your Gitea service and transferred your local code from your computer to the Gitea server.