Gitea Docker Compose Setup: Repositories, SSH, and Backups Done Right

Table of Contents

• Decide rootful or rootless
• Preflight
• Compose service and persistent data
• Reverse proxy and root URL
• First admin and verification
• Backup, update, and rollback
• Common failures
• Frequently Asked Questions

Decide rootful or rootless

Choose the Gitea image family before deployment and keep it consistent. Gitea’s official Docker installation guide warns that rootful and rootless images are not interchangeable. Switching between them without planning can cause ownership and filesystem problems.

For a small internal team, rootful Compose is generally the simpler starting point because the container, bind mount, and host ownership model are easier to inspect. Rootless may better match a host security policy, but it requires the matching image and consistent permissions.

Decision	Operational consequence
Rootful image	Conventional choice for a standard Docker host
Rootless image	Requires the matching rootless image and permissions
Bind mount	Keeps repositories and configuration outside the container
Named volume	Easier Docker management, but less direct inspection

Do not combine a rootful image with a rootless data directory or change image families during an update without a documented migration and verified backup.

Preflight

Before starting the service, choose the image family, reserve the hostname, confirm the ports, and decide where /data will live.

• Confirm Docker Compose is available.
• Choose a stable directory for the Gitea bind mount.
• Select host values for the Gitea UID and GID.
• Decide whether users connect directly or through a reverse proxy.
• Reserve HTTP port 3000 and SSH host port 222.
• Choose SQLite or an externally managed database.
• Record the public web URL and SSH clone address.
• Decide where backups will be stored and how restoration will be tested.

The official guide documents the image, /data volume, and default port mappings. Use it as the baseline for your Compose file: read the Docker installation instructions.

Compose service and persistent data

Mount a durable host directory to /data and publish HTTP and SSH with the required mappings.

services:
  server:
    image: docker.gitea.com/gitea
    container_name: gitea
    environment:
      - USER_UID=${GITEA_UID}
      - USER_GID=${GITEA_GID}
    restart: always
    volumes:
      - ./gitea:/data
    ports:
      - "3000:3000"
      - "222:22"

Save this as compose.yaml, create the gitea directory beside it, and set GITEA_UID and GITEA_GID to values that match the intended ownership model. The container should be replaceable without removing repositories or configuration.

UID/GID and /data

Make the host-mounted directory writable by the identity expected by the selected image. If Gitea starts but cannot create repositories, attachments, or configuration files, inspect ownership and permissions before changing application settings.

id
ls -ld ./gitea
docker compose config

Repository storage and configuration must remain on the persistent mount. A running container does not prove that the mount is writable or that updates will preserve data. The Docker documentation explains the storage layout and image assumptions.

HTTP and SSH URLs

The Compose mapping publishes HTTP on host port 3000 and maps host port 222 to the container’s SSH port 22. When users connect directly, SSH clone URLs must include port 222.

ssh://git@your-host.example:222/team/project.git

The hostname is deployment-specific, but the displayed clone URL must match the address users can reach. If SSH is exposed through another external port, configure Gitea’s public SSH values so generated links remain usable.

Reverse proxy and root URL

Set Gitea’s public root URL to the address users actually enter, particularly when a reverse proxy terminates HTTPS. Gitea may listen internally on port 3000 while users access an HTTPS hostname; both layers must describe the same public service.

A typical arrangement is:

1. The reverse proxy receives HTTPS traffic for the chosen hostname.
2. It forwards requests to Gitea on port 3000.
3. Gitea’s ROOT_URL uses the public HTTPS address.
4. SSH remains reachable through the configured host port.
5. Generated web links and clone URLs are checked after login.

If Gitea generates http://localhost, an internal container name, or an SSH URL with the wrong port, correct the root URL and SSH settings before inviting users. Consult the reverse proxy documentation and configuration cheat sheet.

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 server