Skip to content


Docker files for running gitea

documentation: d-gitea container (you are here)

source code on d-gitea

source code on charlesreid1-docker/d-gitea

gitea documentation - running gitea with docker

Table of Contents

  • secrets
  • app.ini file
  • jinja templates
  • container directory structure
  • container data volume
  • git repositories
  • files mounted into container
  • using the docker-compose.yml file
  • notes on custom files
  • configuring gitea with app.ini
  • customizing gitea with custom files
  • backing up and restoring gitea


There are two secrets that must be set in the Gitea configuration file: the internal token and the secret key.

The two secret values can be placed in two *.secret files:


The contents should be the value of the secret variable you wish to use in custom/conf/app.ini.

These files are not tracked by git.

Jinja Templates

The app.ini script is not stored directly in this repo, since it contains sensitive information. Instead, we store a Jinja template, app.ini.j2, which is rendered into a real app.ini file after variable substitutions, etc.

Normally, we use this repo with Ansible, so we don't deal with the Jinja template ourselves.

If you want to render the Jinja template into a real config file without using Ansible, use the script:

$ ./

(This requires the two secret files mentioned above to be present.)

Container Directory Structure

The custom/ dir in this folder maps to the /data/gitea volume inside the gitea container.

For example, the app.ini configuration file will be mapped into the container at /data/gitea/conf/app.ini.

Container Data Volume

This container expects to use a docker data volume to store the gitea custom configuration and the entire contents of all repositories.

On the host machine, you can access named data volumes at /var/lib/docker/volumes/gitea_gitea/_data or copy files in and out of the container using docker cp.

Git Repositories

directory structure before adding repos to gitea

Directory structure for host-mounted gitea directory before any repositories have been added to gitea:

├── git
│   └── repositories
├── gitea
│   ├── conf
│   │   └── app.ini
│   ├── gitea.db
│   ├── indexers
│   │   └── issues.bleve
│   │       ├── index_meta.json
│   │       └── store
│   ├── lfs
│   ├── log
│   │   ├── gitea.log
│   │   ├── http.log
│   │   └── xorm.log
│   └── sessions
│       └── oauth2
└── ssh [error opening dir]

11 directories, 7 files

directory structure after adding repos to gitea

After adding a repository:

├── git
│   └── repositories
│       └─e charlesreid1
│           └── oieruoweiur.git
│               ├── branches
│               ├── config
│               ├── description
│               ├── HEAD
│               ├── hooks
│               │   ├── applypatch-msg.sample
│               │   ├── commit-msg.sample
│               │   ├── post-receive
│               │   ├── post-receive.d
│               │   │   └── gitea
│               │   ├── post-update.sample
│               │   ├── pre-applypatch.sample
│               │   ├── pre-commit.sample
│               │   ├── prepare-commit-msg.sample
│               │   ├── pre-push.sample
│               │   ├── pre-rebase.sample
│               │   ├── pre-receive
│               │   ├── pre-receive.d
│               │   │   └── gitea
│               │   ├── pre-receive.sample
│               │   ├── update
│               │   ├── update.d
│               │   │   └── gitea
│               │   └── update.sample
│               ├── info
│               │   ├── exclude
│               │   └── refs
│               ├── objects
│               │   ├── info
│               │   │   └── packs
│               │   └── pack
│               └── refs
│                   ├── heads
│                   └── tags
├── gitea
│   ├── conf
│   │   └── app.ini
│   ├── gitea.db
│   ├── indexers
│   │   └── issues.bleve
│   │       ├── index_meta.json
│   │       └── store
│   ├── lfs
│   ├── log
│   │   ├── gitea.log
│   │   ├── http.log
│   │   └── xorm.log
│   └── sessions
│       └── oauth2
└── ssh [error opening dir]

25 directories, 29 files

Backing up git repositories

Backing up git repositories associated with the gitea instance is a separate step from gitea dump (see above).

Before backing up repositories, perform a gitea dump without the repositories included.

All git repositories are stored in /data/git/repositories/. They are stored in the subdirectory org-name/repo-name.

To back up all repositories, copy the folder /data/git/repositories from the gitea container.

To restore all repositories, copy the folder /data/git/repositories into the gitea container.

Files Mounted Into Container

The d-gitea/custom/ directory is mounted into the container at /data/gitea.

The d-gitea/data/ directory is mounted into the container at /app/gitea/data.

To make the custom configuration file, follow the instructions mentioned in the "Secrets" section.

Using the docker-compose.yml File


This directory contains a docker-compose file that can be used to run a gitea server on port 3000.

To get the gitea container up and running,

$ docker-compose up

Now visit <server-ip>:3000. You will be presented with a configuration page. Set up the gitea instance. This will automatically populate the directory structure. See below for more info.

Use this as a project seed to add gitea containers to other docker pods.


The main use of this repo is as a submodule in pod-charlesreid1.

This pod is set up by Ansible, which integrates well with the Jinja template approach.

Notes on Custom Files

The settings in the app.ini file are documented here.

An extensive sample app.ini file is here (WARNING: this broke gitea).

The existing gitea templates are in the gitea repo under templates/. These can be modified as needed and placed in the custom/templates/ directory.

custom templates directory

The templates directory d-gitea/custom/templates contains template files. These are gitea templates that control how particular kinds of gitea pages look. For example, a template can be used to modify how the user page looks, or modify the layout of repository main pages.

In the container, this will be at /data/gitea/templates/.

custom gitea pages

The custom pages directory d-gitea/custom/pages contains one-off pages or static content that is hosted by the gitea instance, but not necessarily incorporated into the gitea site.

For example, a custom "about me" page could be added as a static .html file, and it would be hosted at

In the container, this will be at /data/gitea/pages/.

Backing up and restoring gitea

Running gitea dump command will dump files required for restoring an existing Gitea instance. Unfortunately, gitea's backup and restore functionality is an absolute dumpster fire.

We do our best to walk through the process, but here is a summary: * On the old system: * Create a backup file using the very specific gitea dump incantation that works * Move the backup file out of the gitea container * On the new system: * Unzip the backup file * Put appropriate files in appropriate location * Use the table below to determine where in the repo the gitea dump files should go, and where they will be available inside the gitea container

Creating a Backup

To create a gitea dump, connect to the docker container and get a bash shell as the user git via the docker exec command:

# connect to gitea container
docker exec -it --user git name_of_gitea_container /bin/bash

This will give you a bash shell as the user git. Now create a gitea dump file (the gitea dump command requires you to be in /app/gitea, this assumes that the gitea executable is at the default location of /app/gitea/gitea):

# necessary
cd /app/gitea
# create gitea dump
/app/gitea/gitea dump --file --skip-repository

IMPORTANT: The --skip-repositories flag means we are making the gitea dump way, way, way smaller, but it also means we need to back up and restore the repositories folder ourselves! (See below for instructions.)

Now copy the file out of the container, then remove it from the container:

# copy gitea dump out of container
docker cp name_of_gitea_container:/app/gitea/ .

# remove gitea dump
docker exec -it name_of_gitea_container rm /app/gitea/

Contents of Dump File

When the gitea dump file is unzipped, it will create the following files:

  • app.ini
  • custom/ directory
  • log/ directory (useless duplicate, already contained in custom/ dir)
  • data/ directory

These files should map to the following locations in the docker container running the live gitea instance:

gitea dump file:        gitea live instance:
----------------        --------------------
app.ini                 /data/gitea/conf/app.ini
custom/                 /data/gitea/
log/                    (useless duplicate of custom/log/)
data                    /app/gitea/data

Restoring a Backup

To restore a backup, copy the following files from the gitea dump to the following locations inside this repository:

gitea dump file:        d-gitea repo location:
----------------        ----------------------
app.ini                 d-gitea/custom/conf/app.ini
custom/*                d-gitea/custom/*
data                    d-gitea/data

(If you're running pod-charlesreid1, put these files in the specified location in the d-gitea submodule.)

Restoring repositories directory

Note that when we created the gitea dump, we excluded the repositories themselves. This is because these will greatly inflate the size of our gitea dump and will make it much more difficult to store our backup files.

Repository contents can be backed up separately as follows:

  • Log in to the old server
  • Back up the /data/git/repositories directory (copy and compress)
  • Copy the backup to the new server
  • Log in to the new server
  • Mount the /data/git/repositories folder

Optionally, if you want to keep the repositories folder in its own location, modify docker-compose.yml to add the following line to the gitea container's volumes configuration:

    image: gitea/gitea:latest


      - "/path/to/repositories:/data/git/repositories"


This should make it easier to manage, back up, and restore the repositories folder.

Database backups

We opt for the SQLite backend for gitea, which means the database is kept in a flat file on disk called /data/gitea/gitea.db.

The location of this file and the format of the database are specified in the config file in d-gitea/custom/conf/app.ini.

This file should not be edited, instead change the Jinja template d-gitea/custom/conf/app.ini.j2 and remake app.ini from the template.