nerd-monitor/GITEA_RUNNER_DOCKER.md

Gitea Runner Docker Configuration Guide

Since your Gitea runner is running in Docker itself, this guide explains how to properly configure it for Docker builds (Docker-in-Docker).

The Issue

When the Gitea runner runs in a Docker container, it needs:

1. Docker CLI to be installed in the runner container
2. Docker socket access to communicate with the host Docker daemon
3. Proper environment setup for Docker-in-Docker to work

Solution: Docker-in-Docker Setup

For Docker Compose Runners

If your Gitea runner is running via Docker Compose, update your docker-compose configuration:

services:
  gitea-runner:
    image: gitea/act_runner:latest
    container_name: gitea-runner
    environment:
      GITEA_INSTANCE_URL: https://git.nerdnest.dev
      GITEA_RUNNER_REGISTRATION_TOKEN: your-token-here
      GITEA_RUNNER_NAME: gitea-runner-1
      GITEA_RUNNER_LABELS: ubuntu-latest
    volumes:
      # Mount the Docker socket for Docker-in-Docker
      - /var/run/docker.sock:/var/run/docker.sock
      # Optional: Mount Docker socket with writable permissions
      - /var/run/docker.sock:/var/run/docker.sock:rw
    networks:
      - gitea-network
    restart: always

Key Configuration

The critical part is the volume mount:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

This gives the runner container access to the host's Docker daemon, allowing it to build Docker images.

Step-by-Step Setup

1. Update Your Runner's Docker Compose File

If you're using docker-compose to run your Gitea runner:

# Find your runner's docker-compose.yml
# Usually something like: /root/gitea-runner/docker-compose.yml
# Or: ~/gitea/docker-compose.yml

Update the runner service to include the Docker socket mount:

services:
  runner:
    image: gitea/act_runner:latest
    container_name: gitea-runner
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # Add this line
      - ./runner-data:/data  # If you have a data volume
    environment:
      GITEA_INSTANCE_URL: https://git.nerdnest.dev
      GITEA_RUNNER_REGISTRATION_TOKEN: your-token
    restart: unless-stopped

2. Restart the Runner

# Navigate to your runner's docker-compose directory
cd /path/to/runner

# Stop the current runner
docker-compose down

# Start it again with the updated configuration
docker-compose up -d

# Verify it's running
docker-compose ps

3. Check Docker Access

Verify the runner has Docker access:

# SSH into the runner container
docker exec -it gitea-runner sh

# Check if Docker is available
docker --version
docker ps

# If these work, Docker is properly configured

What Happens After Configuration

Once Docker socket is properly mounted:

1. Binary builds: Work as before ✓
2. Docker image builds: Will now succeed ✓
3. Release artifacts: Will include Docker images ✓

The workflow will:

• Build all platform binaries
• Build server Docker image
• Build agent Docker image
• Save images as .tar files
• Upload everything to the release

Workflow Behavior

The updated workflow now:

1. Waits for Docker daemon with a 30-second timeout
2. Properly detects Docker using docker info instead of docker --version
3. Builds images when Docker is available
4. Gracefully skips if Docker is unavailable

Troubleshooting

"Docker daemon is not available" warning in logs

Problem: Runner started but Docker socket isn't mounted

Solution:

1. Check your docker-compose.yml has the socket mount
2. Verify the path /var/run/docker.sock exists on host
3. Restart the runner: docker-compose restart
4. Check the logs: docker-compose logs -f runner

Permission denied when building Docker images

Problem: Docker socket exists but runner can't access it

Solution:

# Fix Docker socket permissions on the host
sudo chmod 666 /var/run/docker.sock

# Or restart Docker daemon
sudo systemctl restart docker

"docker: command not found" in runner container

Problem: Docker CLI isn't installed in the runner image

Solution: The official gitea/act_runner:latest image should have Docker CLI pre-installed. If not, use a different base image or switch to gitea/act_runner:nightly which has better Docker support.

Images build locally but fail in runner

Problem: Docker works in runner but builds fail

Check:

1. Do you have enough disk space in Docker? docker system df
2. Are the Dockerfiles correct? docker build -f Dockerfile.server .
3. Is the working directory correct in runner? Check logs

Complete Example docker-compose.yml

version: '3.8'

services:
  gitea-runner:
    image: gitea/act_runner:latest
    container_name: gitea-runner
    hostname: gitea-runner
    environment:
      # Gitea configuration
      GITEA_INSTANCE_URL: https://git.nerdnest.dev
      GITEA_RUNNER_REGISTRATION_TOKEN: ${GITEA_RUNNER_TOKEN}
      GITEA_RUNNER_NAME: gitea-runner-1
      GITEA_RUNNER_LABELS: ubuntu-latest
      # Optional: for custom work directory
      GITEA_RUNNER_WORK_DIR: /data/runner
    volumes:
      # IMPORTANT: Docker socket for building images
      - /var/run/docker.sock:/var/run/docker.sock
      # Runner data storage
      - ./runner-data:/data
    restart: unless-stopped
    networks:
      - gitea

networks:
  gitea:
    driver: bridge

Testing the Setup

After updating the configuration:

1. Push to master:

   git push origin master
   

2. Create a test tag:

   git tag -a v0.0.4 -m "Docker build test"
   git push origin v0.0.4
   

3. Monitor in Actions tab:

   • Binary builds should complete
   • Docker images should now build successfully
   • Look for "✓ Server image built and saved"
   • Look for "✓ Agent image built and saved"

4. Verify in Releases tab:

   • All binaries present
   • SHA256SUMS file present
   • Docker image .tar files present

Additional Notes

• Docker-in-Docker allows the runner to build Docker images
• Socket mounting is safer than running Docker privileged
• No rebuilds needed - just restart the container
• All other builds (binaries, checksums) continue to work

Support & References

• Gitea Runner Documentation
• Docker Socket Mounting
• Docker-in-Docker Guide