DEV Community

Cover image for The Definitive Guide to _safe_ Docker-in-Docker with Gitea Actions
Tony Miller
Tony Miller

Posted on

The Definitive Guide to _safe_ Docker-in-Docker with Gitea Actions

#docker #gitea #githubactions #dockercompose

The Definitive Guide to Docker-in-Docker with Gitea Actions

It has come to my attention that someone is wrong on the Internet. Actually, not just someone—seemingly everyone writing guides about setting up Docker-in-Docker (DIND) with Gitea Actions. The multitudes of tutorials, blog posts, and StackOverflow answers all seem to miss critical architectural limitations and security considerations that make their solutions either incomplete, insecure, or simply non-functional in real-world scenarios.

This guide presents a complete, almost production-ready example for isolated Docker-in-Docker CI/CD using Gitea Actions with proper security boundaries and full functionality.

You can find all the examples mentioned here in this repository on GitHub

⚠️ Enterprise Security Warning

This setup is intended for development and testing environments. For true enterprise-grade production deployments, additional security measures are required:

Critical Security Enhancements Needed for Enterprise-grade Production

  1. Network Firewall Protection

    • Deploy firewall rules to isolate the CI/CD network from internal corporate networks
    • Implement egress filtering to prevent build containers from accessing internal services
    • Use network segmentation to contain potential container breakouts
    • Consider running the entire stack in a separate VLAN or VPC

  2. Container Image Security

    • Gitea needs a feature that only white listed images are allowed to run in priveleged-mode
    • Only allow pre-approved, security-scanned base images
    • Implement image signing and verification workflows
    • Regular vulnerability scanning of all container images

  3. DIND Image Hardening

    • Remove unnecessary packages and tools from the custom DIND image
    • Implement read-only root filesystem where possible
    • Use distroless or minimal base images

  4. Plenty more with various compliance stuff but the above state is a good start.

The configuration presented here prioritizes functionality and ease of setup over maximum security hardening.

Requirements & Use Case

We need a CI/CD environment that provides:

  • Complete isolation from the host Docker daemon
  • Docker functionality available to both services and build steps
  • Self-contained deployment with no external dependencies
  • Proper security boundaries between jobs and the host system
  • Full Docker API access for build, test, and deployment workflows

The Problem: Gitea Actions Limitations

Gitea's act_runner is based on the excellent nektos/act project, but it has several critical limitations when compared to GitHub Actions:

1. Incomplete Services Support

  • Incomplete volumes mounting capability for services in workflow YAML
  • Limited options support compared to full docker run functionality
  • No command override support in the services: section

2. Docker Configuration Challenges

  • Cannot mount daemon.json configuration files into service containers
  • No way to inject custom Docker daemon startup parameters
  • Services are treated as immutable "black boxes"

3. GitHub Actions Parity Issues

GitHub Actions itself doesn't support:

  • command overrides in the services: section

Why Custom DIND Images Are Required

Standard docker:dind images:

  • Listen on Unix socket by default (/var/run/docker.sock)
  • Have TLS enabled by default (requires certificates)
  • Cannot be configured via environment variables for network settings
  • Cannot be customized through workflow YAML due to services limitations

Our solution: Build a custom DIND image with hardcoded configuration:

FROM docker:dind
CMD ["dockerd", "--host", "tcp://0.0.0.0:2376", "--tls=false"]
Enter fullscreen mode Exit fullscreen mode

Architecture Overview: Triple-Nested Isolation

Our architecture provides three layers of Docker isolation:

  1. Host Docker (docker-compose level) - Orchestrates the entire CI/CD stack
  2. Runner DIND (act_runner execution environment) - Provides Docker services for workflows
  3. Build DIND (workflow build steps) - Enables Docker operations within build containers

This triple nesting is essential because:

  • Services run in the runner's Docker daemon
  • Build steps run inside containers with no Docker daemon access
  • Each layer provides different security boundaries and functional contexts

Step-by-Step Implementation

Step 1: Create the Custom DIND Image

Dockerfile:

FROM docker:dind

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD docker version || exit 1

CMD ["dockerd", "--host", "tcp://0.0.0.0:2376", "--tls=false"]
Enter fullscreen mode Exit fullscreen mode

Step 2: Configure Gitea for Actions

⚠️ Security Note: The INTERNAL_TOKEN and JWT_SECRET values in the example app.ini below are provided for convenience to make this docker-compose example work out-of-the-box. In production deployments, these tokens MUST be regenerated using fresh, cryptographically secure random values. Never use these example tokens in any environment beyond local development and testing.

app.ini:

APP_NAME = Gitea: Git with a cup of tea
RUN_MODE = prod
WORK_PATH = /data/gitea

[actions]
ENABLED = true

[repository]
ROOT = /data/git/repositories

[repository.local]
LOCAL_COPY_PATH = /data/gitea/tmp/local-repo

[repository.upload]
TEMP_PATH = /data/gitea/uploads

[server]
APP_DATA_PATH = /data/gitea
DOMAIN = localhost
SSH_DOMAIN = localhost
HTTP_PORT = 3000
ROOT_URL = http://localhost:3000
LOCAL_ROOT_URL= http://gitea:3000
DISABLE_SSH = false
SSH_PORT = 2222
SSH_LISTEN_PORT = 22
LFS_START_SERVER = false

[database]
PATH = /data/gitea/gitea.db
DB_TYPE = sqlite3
HOST = localhost:3306
NAME = gitea
USER = root
PASSWD = 
LOG_SQL = false

[indexer]
ISSUE_INDEXER_PATH = /data/gitea/indexers/issues.bleve

[session]
PROVIDER_CONFIG = /data/gitea/sessions

[picture]
AVATAR_UPLOAD_PATH = /data/gitea/avatars
REPOSITORY_AVATAR_UPLOAD_PATH = /data/gitea/repo-avatars

[attachment]
PATH = /data/gitea/attachments

[log]
MODE = console
LEVEL = info
ROOT_PATH = /data/gitea/log

[security]
INSTALL_LOCK = true
REVERSE_PROXY_LIMIT = 1
REVERSE_PROXY_TRUSTED_PROXIES = *
INTERNAL_TOKEN = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYmYiOjE3NTY0NzI0OTF9.lXfJEgeQCkXcQx3VKm-TwLQktTYrccm_JK1P0xiDmEw

[service]
DISABLE_REGISTRATION = false
REQUIRE_SIGNIN_VIEW = false

[lfs]
PATH = /data/git/lfs

[oauth2]
JWT_SECRET = nq7Fpd5bAPFHOWHZJJah2rKfXdC3pKaF0pMgtaQwAdw
Enter fullscreen mode Exit fullscreen mode

Step 3: Docker Compose Configuration

The complete docker-compose.yml orchestrates six services with proper dependency management:

docker-compose.yml:

services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    ports:
      - "3000:3000"
      - "2222:22"
    volumes:
      - gitea_data:/data
      - ./app.ini:/data/gitea/conf/app.ini:ro
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    environment:
      - USER_UID=1000
      - USER_GID=1000
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped

  dind:
    build: .
    container_name: dind
    privileged: true
    volumes:
      - dind_data:/var/lib/docker
    environment:
      - DOCKER_HOST=tcp://localhost:2376
    healthcheck:
      test: ["CMD", "docker", "info"]
      interval: 10s
      timeout: 10s
      retries: 5
      start_period: 30s
    restart: unless-stopped

  registry:
    image: registry:2
    container_name: registry
    volumes:
      - registry_data:/var/lib/registry
    environment:
      - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:5000/v2/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    restart: unless-stopped

  image-builder:
    image: docker:dind
    container_name: image-builder
    depends_on:
      registry:
        condition: service_healthy
      dind:
        condition: service_healthy
    volumes:
      - ./Dockerfile:/workspace/Dockerfile
      - dind_data:/var/lib/docker
    working_dir: /workspace
    command: >
      sh -c "
        export DOCKER_HOST=tcp://dind:2376
        export DOCKER_TLS_VERIFY=\"\"
        echo 'Building and pushing DIND image to local registry...'
        docker build -t registry:5000/dind-plain:latest .
        docker push registry:5000/dind-plain:latest
        echo 'Image build and push complete!'
      "
    restart: "no"

  runner-configurator:
    image: gitea/gitea:latest
    container_name: runner-configurator
    depends_on:
      gitea:
        condition: service_healthy
    volumes:
      - runner_config:/config
      - ./app.ini:/data/gitea/conf/app.ini:ro
    command: >
      sh -c "
        echo 'Gitea is healthy, proceeding...'
        echo 'Generating runner token...'
        su - git -c 'cd /data && /usr/local/bin/gitea actions generate-runner-token' > /config/token
        echo 'Creating runner config...'
        GITEA_IP=$$(getent hosts gitea | awk '{print $$1}')
        REGISTRY_IP=$$(getent hosts registry | awk '{print $$1}')
        echo \"Resolved Gitea IP: $$GITEA_IP\"
        cat > /config/config.yaml << EOF
      log:
        level: info
      runner:
        file: .runner
        capacity: 1
        timeout: 3h
        insecure: false
        fetch_timeout: 5s
        fetch_interval: 2s
        labels:
          - 'ubuntu-latest:docker://gitea/runner-images:ubuntu-latest'
          - 'ubuntu-22.04:docker://gitea/runner-images:ubuntu-22.04'
          - 'ubuntu-20.04:docker://gitea/runner-images:ubuntu-20.04'
          - 'linux:docker://gitea/runner-images:ubuntu-latest'
      cache:
        enabled: true
        dir: '/tmp/cache'
        host: ''
        port: 0
      container:
        network_mode: bridge
        enable_ipv6: false
        privileged: true
        valid_volumes:
          - '**'
        docker_host: tcp://dind:2376
        options: '--add-host=gitea:$$GITEA_IP --add-host=registry:$$REGISTRY_IP'
      host:
        workdir_parent: /tmp
      EOF
        echo 'Configuration complete!'
      "
    restart: "no"

  admin-setup:
    image: gitea/gitea:latest
    container_name: admin-setup
    depends_on:
      gitea:
        condition: service_healthy
    environment:
      - GITEA_URL=http://gitea:3000
    volumes:
      - gitea_data:/data
      - ./app.ini:/data/gitea/conf/app.ini:ro
    command: >
      sh -c "
        echo 'Creating admin user...'
        su - git -c '/usr/local/bin/gitea admin user create --admin --username admin --password admin --email admin@localhost.local --must-change-password=false' || echo 'Admin user already exists'
        echo 'Admin setup complete!'
      "
    restart: "no"

  runner:
    image: gitea/act_runner:latest
    container_name: runner
    depends_on:
      gitea:
        condition: service_healthy
      dind:
        condition: service_healthy
      admin-setup:
        condition: service_completed_successfully
      runner-configurator:
        condition: service_completed_successfully
      image-builder:
        condition: service_completed_successfully
    volumes:
      - runner_config:/config:ro
      - runner_data:/data
    environment:
      - DOCKER_HOST=tcp://dind:2376
      - DOCKER_TLS_VERIFY=""
      - GITEA_INSTANCE_URL=http://gitea:3000
      - GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/config/token
      - CONFIG_FILE=/config/config.yaml
    command: >
      sh -c "
        echo 'All dependencies ready, token file available...'
        echo 'Registering and starting runner...'
        act_runner register --config /config/config.yaml --no-interactive
        act_runner daemon --config /config/config.yaml
      "
    restart: unless-stopped

volumes:
  gitea_data:
  dind_data:
  runner_config:
  runner_data:
  registry_data:
Enter fullscreen mode Exit fullscreen mode

Step 4: Example Workflow

.gitea/workflows/test-dind.yml:

name: Test DIND Integration

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

jobs:
  test-docker:
    runs-on: linux

    services:
      docker:
        image: registry:5000/dind-plain:latest

    env:
      DOCKER_HOST: tcp://docker:2376
      DOCKER_TLS_VERIFY: ""

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Wait
        run: sleep 10

      - name: Verify Docker daemon is running
        run: |
          echo "Testing Docker daemon connection..."
          docker info

      - name: List running containers
        run: |
          echo "Listing all containers..."
          docker ps -a

      - name: Test Docker functionality
        run: |
          echo "Testing basic Docker operations..."
          docker run --rm hello-world

      - name: Verify DIND isolation
        run: |
          echo "Testing container isolation..."
          docker run --rm alpine:latest echo "DIND is working perfectly!"
Enter fullscreen mode Exit fullscreen mode

Security Considerations

This architecture provides multiple security boundaries:

  • Host Isolation: Docker-compose isolates the entire CI/CD stack from the host
  • Runner Isolation: Each workflow job gets its own Docker environment
  • Build Isolation: Docker operations in build steps use separate DIND instances
  • Network Isolation: Partial. Services and builds cannot directly access host resources but can access host network.

Conclusion

This guide provides a complete examplt of a production-ready solution for Docker-in-Docker with Gitea Actions. The architecture addresses the fundamental limitations of both GitHub Actions and Gitea's act_runner while providing proper security isolation and full Docker functionality.

The key insights that most guides miss:

  1. Custom DIND images are required due to services configuration limitations
  2. Triple-nested isolation provides both security and functionality

Top comments (0)