# 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:

```yaml
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:
```yaml
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:

```bash
# 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:

```yaml
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

```bash
# 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:

```bash
# 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**:
```bash
# 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

```yaml
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**:
   ```bash
   git push origin master
   ```

2. **Create a test tag**:
   ```bash
   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](https://gitea.com/gitea/act_runner)
- [Docker Socket Mounting](https://docs.docker.com/engine/reference/commandline/run/#mount-volume--v---volume)
- [Docker-in-Docker Guide](https://www.docker.com/blog/docker-socket-v2-work-docker-run-again/)