How to Fix Gitea Docker Deployment Error

In this tutorial, you'll learn about How to Fix Gitea Docker Deployment Error. We cover key concepts, practical examples, and best practices.

Gitea Docker container exits immediately with exit code 1 or the web UI shows 500 — database error after starting the container — the Gitea Docker deployment has configuration or permission issues.

The Problem

$ docker logs gitea
2026/06/24 10:00:00 [...] cmd/web.go:102:runWeb() [E] Failed to initialize database:
dial tcp 127.0.0.1:3306: connect: connection refused

Step-by-Step Fix

Step 1: Use the correct compose file

version: "3"
services:
  gitea:
    image: gitea/gitea:latest
    ports:
      - "3000:3000"
      - "22:22"
    volumes:
      - gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
volumes:
  gitea_data:

Step 2: Fix volume permissions

sudo chown -R 1000:1000 /var/lib/docker/volumes/gitea_data/_data

Step 3: Check database connection

docker exec -it gitea gitea doctor --all

Expected output:

[INFO] Checking database connection... OK
[INFO] All checks passed.

Step 4: View logs in real time

docker logs -f gitea

Prevention Tips

• Pin the Gitea Docker image version in production
• Use an external database instead of SQLite for production
• Set USER_UID and USER_GID to match the host user
• Mount /etc/localtime to keep container time in sync

Common Mistakes with docker deploy

1. Forgetting deriving (Show, Eq) on custom data types needed for debugging
2. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
3. Using head and tail instead of pattern matching, causing runtime errors on empty lists

These mistakes appear frequently in real-world GITEA code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ