Gitea is a self-hosted git service written in Go, it's super lightweight to run and supports ARM architectures as well, so you can run it on a Raspberry Pi as well.
What are we doing today
In this tutorial we will be setting up a self hosted version control repository with Gitea on Docker using Traefik as our Load Balancer and SSL terminations for LetsEncrypt certificates.
We will then create a example git repository, add our ssh key to our account and clone our repository using ssh, change some code, commit and push to our repository.
Assumptions
I will assume that you have docker and docker-compose installed. If you need more info on Traefik you can have a look at their website, but I have also written a post on setting up Traefik v2 in detail, but we will touch on that in this post.
Environment Details
I have 1 DNS entry set to the following:
- Traefik:
traefik.rbkr.xyz - Gitea:
git.rbkr.xyz
Accessing our service will be done over HTTPS on port 443, and for cloning over SSH, the port will be set to 222
Directory Structure
Create the gitea directory which will be our docker compose project directory:
mkdir gitea
cd gitea
Create the traefik directory for acme.json where certificate data will be stored, create the file and change permissions on the file:
touch traefik/acme.json
chmod 600 traefik/acme.json
Traefik
Open the docker-compose.yml and add the first bit which will Traefik, ensure that you replace the following:
-
me@example.comwith your email undercertificatesResolvers.letsencrypt.acme.email -
traefik.rbkr.xyzwith your fqdn for traefik undertraefik.http.routers.api.rule=Host()
The section for traefik:
version: '3.8'
services:
gitea-traefik:
image: traefik:2.4
container_name: gitea-traefik
restart: unless-stopped
volumes:
- ./traefik/acme.json:/acme.json
- /var/run/docker.sock:/var/run/docker.sock
networks:
- public
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.api.rule=Host(`traefik.rbkr.xyz`)'
- 'traefik.http.routers.api.entrypoints=https'
- 'traefik.http.routers.api.service=api@internal'
- 'traefik.http.routers.api.tls=true'
- 'traefik.http.routers.api.tls.certresolver=letsencrypt'
ports:
- 80:80
- 443:443
command:
- '--api'
- '--providers.docker=true'
- '--providers.docker.exposedByDefault=false'
- '--entrypoints.http=true'
- '--entrypoints.http.address=:80'
- '--entrypoints.http.http.redirections.entrypoint.to=https'
- '--entrypoints.http.http.redirections.entrypoint.scheme=https'
- '--entrypoints.https=true'
- '--entrypoints.https.address=:443'
- '--certificatesResolvers.letsencrypt.acme.email=me@example.com`'
- '--certificatesResolvers.letsencrypt.acme.storage=acme.json'
- '--certificatesResolvers.letsencrypt.acme.httpChallenge.entryPoint=http'
- '--log=true'
- '--log.level=INFO'
logging:
driver: "json-file"
options:
max-size: "1m"
networks:
public:
name: public
```
We can start traefik so long:
```bash
docker-compose up -d
```
## Gitea
Now we will add the Gitea components, I have opted in for the gitea service and a redis cache and will be making use of sqlite as this is just a demonstration. For non-test environments, you can have a look at MySQL or Postres:
- https://docs.gitea.io/en-us/install-with-docker/#databases
Review the following configuration options:
- `DOMAIN` and `SSH_DOMAIN` (this will be used in your clone urls)
- `ROOT_URL` (this is set to use the HTTPS protocol, including my domain)
- `SSH_LISTEN_PORT` (this is the port listening for SSH inside the container)
- `SSH_PORT` (this is the port we are exposing from outside, which will be replaced in the clone url)
- `DB_TYPE` (Im using sqlite for this example)
- `traefik.http.routers.gitea.rule=Host()` (the host header to reach gitea via web)
- `./data/gitea` (I am persisting the data in my local working directory under the given path)
The gitea portion of the `docker-compose.yml`:
```yaml
---
version: '3.8'
services:
...
gitea:
container_name: gitea
image: gitea/gitea:${GITEA_VERSION:-1.14.5}
restart: unless-stopped
depends_on:
gitea-traefik:
condition: service_started
gitea-cache:
condition: service_healthy
environment:
- APP_NAME="Gitea"
- USER_UID=1000
- USER_GID=1000
- USER=git
- RUN_MODE=prod
- DOMAIN=git.rbkr.xyz
- SSH_DOMAIN=git.rbkr.xyz
- HTTP_PORT=3000
- ROOT_URL=https://git.rbkr.xyz
- SSH_PORT=222
- SSH_LISTEN_PORT=22
- DB_TYPE=sqlite3
- GITEA__cache__ENABLED=true
- GITEA__cache__ADAPTER=redis
- GITEA__cache__HOST=redis://gitea-cache:6379/0?pool_size=100&idle_timeout=180s
- GITEA__cache__ITEM_TTL=24h
ports:
- "222:22"
networks:
- public
volumes:
- ./data/gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
labels:
- "traefik.enable=true"
- "traefik.http.routers.gitea.rule=Host(`git.rbkr.xyz`)"
- "traefik.http.routers.gitea.entrypoints=https"
- "traefik.http.routers.gitea.tls.certresolver=letsencrypt"
- "traefik.http.routers.gitea.service=gitea-service"
- "traefik.http.services.gitea-service.loadbalancer.server.port=3000"
logging:
driver: "json-file"
options:
max-size: "1m"
gitea-cache:
container_name: gitea-cache
image: redis:6-alpine
restart: unless-stopped
networks:
- public
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 15s
timeout: 3s
retries: 30
logging:
driver: "json-file"
options:
max-size: "1m"
...
```
So my complete `docker-compose.yml` will look like the following:
```yaml
---
version: '3.8'
services:
gitea-traefik:
image: traefik:2.4
container_name: gitea-traefik
restart: unless-stopped
volumes:
- ./traefik/acme.json:/acme.json
- /var/run/docker.sock:/var/run/docker.sock
networks:
- public
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.api.rule=Host(`traefik.rbkr.xyz`)'
- 'traefik.http.routers.api.entrypoints=https'
- 'traefik.http.routers.api.service=api@internal'
- 'traefik.http.routers.api.tls=true'
- 'traefik.http.routers.api.tls.certresolver=letsencrypt'
ports:
- 80:80
- 443:443
command:
- '--api'
- '--providers.docker=true'
- '--providers.docker.exposedByDefault=false'
- '--entrypoints.http=true'
- '--entrypoints.http.address=:80'
- '--entrypoints.http.http.redirections.entrypoint.to=https'
- '--entrypoints.http.http.redirections.entrypoint.scheme=https'
- '--entrypoints.https=true'
- '--entrypoints.https.address=:443'
- '--certificatesResolvers.letsencrypt.acme.email=me@example.com'
- '--certificatesResolvers.letsencrypt.acme.storage=acme.json'
- '--certificatesResolvers.letsencrypt.acme.httpChallenge.entryPoint=http'
- '--log=true'
- '--log.level=INFO'
logging:
driver: "json-file"
options:
max-size: "1m"
gitea:
container_name: gitea
image: gitea/gitea:${GITEA_VERSION:-1.14.5}
restart: unless-stopped
depends_on:
gitea-traefik:
condition: service_started
gitea-cache:
condition: service_healthy
environment:
- APP_NAME="Gitea"
- USER_UID=1000
- USER_GID=1000
- USER=git
- RUN_MODE=prod
- DOMAIN=git.rbkr.xyz
- SSH_DOMAIN=git.rbkr.xyz
- HTTP_PORT=3000
- ROOT_URL=https://git.rbkr.xyz
- SSH_PORT=222
- SSH_LISTEN_PORT=22
- DB_TYPE=sqlite3
- GITEA__cache__ENABLED=true
- GITEA__cache__ADAPTER=redis
- GITEA__cache__HOST=redis://gitea-cache:6379/0?pool_size=100&idle_timeout=180s
- GITEA__cache__ITEM_TTL=24h
ports:
- "222:22"
networks:
- public
volumes:
- ./data/gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
labels:
- "traefik.enable=true"
- "traefik.http.routers.gitea.rule=Host(`git.rbkr.xyz`)"
- "traefik.http.routers.gitea.entrypoints=https"
- "traefik.http.routers.gitea.tls.certresolver=letsencrypt"
- "traefik.http.routers.gitea.service=gitea-service"
- "traefik.http.services.gitea-service.loadbalancer.server.port=3000"
logging:
driver: "json-file"
options:
max-size: "1m"
gitea-cache:
container_name: gitea-cache
image: redis:6-alpine
restart: unless-stopped
networks:
- public
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 15s
timeout: 3s
retries: 30
logging:
driver: "json-file"
options:
max-size: "1m"
networks:
public:
name: public
```
Once your configuration is updated, start gitea:
```bash
docker-compose up -d
Creating network "public" with the default driver
Creating gitea-traefik ... done
Creating gitea-cache ... done
Creating gitea ... done
```
Once the containers has started, verify that they are all up:
```bash
docker-compose ps
Name Command State Ports
--------------------------------------------------------------------------------------------------------------------------------------
gitea /usr/bin/entrypoint /bin/s ... Up 0.0.0.0:222->22/tcp,:::222->22/tcp, 3000/tcp
gitea-cache docker-entrypoint.sh redis ... Up (healthy) 6379/tcp
gitea-traefik /entrypoint.sh --api --pro ... Up 0.0.0.0:443->443/tcp,:::443->443/tcp, 0.0.0.0:80->80/tcp,:::80->80/tcp
```
## Installation and Configuration
Head over to the `ROOT_URL` of your gitea installation, in my case it looked like the following:
If you are not automatically redirected to register an account, select "Register" in the top right side:
If you would like to make use of email, configure your email settings here:
Then configure the admin account:
Once you are logged in, you should see the following screen:
## SSH Key
Now we would like to create a SSH key so that we can authorize our git client to pull and push to/from Gitea:
```bash
ssh-keygen -f ~/.ssh/gitea-demo -t rsa -C "Gitea-Demo" -q -N ""
```
Then head to your profile, select settings:
Select the SSH Tab and select "Add Key":
Head back to your terminal and copy your public ssh key from the key that we created earlier:
```bash
cat ~/.ssh/gitea-demo.pub
ssh-rsa AAAAB[x----redacted----x]/en5QDz3vI18n1u4lrKu1YsTR57YL Gitea-Demo
```
Then paste the public key into the form and add the key, you should then see the key present in gitea:
## Create a Git Repository
Now head back to the "Dashboard", then select the "+" sign at the top and create a "New Repository":
From the repo form, I will be naming my repository "hello-world":
Then I selected "Initialise repository with Readme" and I selected to create the repository:
Now when we select the repo, we should see it in the Gitea UI:
To clone the repository via SSH, select the "SSH" button and click copy to clipboard:
Before we clone the repo on our terminal, let's setup the ssh-agent to be active for 1 hour:
```
eval $(ssh-agent -t 3600)
```
Then add the ssh key to the ssh-agent:
```
ssh-add ~/.ssh/gitea-demo
Identity added: ~/.ssh/gitea-demo (Gitea-Demo)
```
*Optional:* If you have a non default ssh key, like the above and you don't want to make use of `ssh-agent` you can setup a SSH Config, for example in `~/.ssh/config`:
```
# Globals
Host *
StrictHostKeyChecking no
UserKnownHostsFile /dev/null
#AddKeysToAgent yes
#IdentityFile ~/.ssh/id_rsa
ServerAliveInterval 60
ServerAliveCountMax 30
# Gitea
Host git.rbkr.xyz
IdentityFile ~/.ssh/gitea-demo
User git
Port 222
```
Now let's clone the repository:
```
git clone ssh://git@git.rbkr.xyz:222/ruanbekker/hello-world.git
Cloning into 'hello-world'...
Warning: Permanently added '[git.rbkr.xyz]:222,[95.x.x.x]:222' (ECDSA) to the list of known hosts.
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.
```
Change into the directory which we cloned:
```
cd hello-world
```
Let's update the `README.md` file with any content, then after we saved the file, we can see that the file has been changed:
```
git status
On branch master
Your branch is up to date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: README.md
no changes added to commit (use "git add" and/or "git commit -a")
```
Add the file, commit and push to master:
```
git add README.md
git commit -m "Update readme for blogpost"
git push origin master
Writing objects: 100% (3/3), 305 bytes | 305.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
remote: . Processing 1 references
remote: Processed 1 references in total
To ssh://git.rbkr.xyz:222/ruanbekker/hello-world.git
7804b67..85550dd master -> master
```
## View the changes
When we head back to the Gitea UI, we can see the README file has been updated, and we can see a git commit sha as well:
In order to see what changed, we can click on the git commit sha:
## Swagger API
Gitea ships with Swagger by default and the endpoint is `/api/swagger` which in my case is accessible via:
- https://git.rbkr.xyz/api/swagger
And it looks like the following:
## Thank You
I hope this was helpful, I was really impressed with Gitea. If you liked this content, please make sure to share or come say hi on my website or twitter:
* **Website**: [ruan.dev](https://ruan.dev)
* **Twitter**: [@ruanbekker](https://twitter.com/ruanbekker)
Top comments (1)
Hey, thanks for the great article.
How do I remove the need to add :222 to the clone ssh url ?
Is there a way to use 22 instead ?
Do I simply need to make sshd listen on another port to let gitea use it ?
Or can I somehow make them both use it ?