Arpad Krejczinger
12ff0e15bd
- Document common Docker issues and filesystem permission problems - Include service management and configuration validation steps - Provide systematic debugging approach for Gitea deployment issues
87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# Gitea Docker Troubleshooting - Complete Resolution
|
|
|
|
## The Problem
|
|
Gitea container failing with: `s6-svscan: fatal: unable to open .s6-svscan/lock: Read-only file system`
|
|
|
|
## Root Cause Analysis
|
|
The issue was **Docker security hardening interfering with Gitea's s6-overlay init system**.
|
|
|
|
### What Broke Gitea
|
|
1. **`read_only: true`** - Prevented s6-overlay from creating lock files
|
|
2. **`user: "1000:1000"`** - Forced non-root start, breaking s6-overlay initialization
|
|
3. **`Missing config values`**
|
|
- GITEA__server__ROOT_URL=https://ak-homelab.duckdns.org/gitea/
|
|
- GITEA__server__SSH_PORT=2223
|
|
4. **`Overy restrictive port config`**
|
|
- "127.0.0.1:3000:3000" # Web UI localhost only: ok, since requests come in via reverse proxy
|
|
- "127.0.0.1:2223:22" # Git port on localhost: NOT OK, this prevents git push/pull from outside
|
|
- "2223:22" # <- Fixed config
|
|
5. **Overly restrictive security caps** - Prevented proper container initialization
|
|
|
|
### Key Understanding: s6-overlay Init System
|
|
Gitea uses s6-overlay which requires:
|
|
1. **Start as root** to set up supervision tree and create lock files
|
|
2. **Then drop privileges** to user specified by `USER_UID`/`USER_GID` environment variables
|
|
|
|
Setting `user: "1000:1000"` at Docker level bypassed this process.
|
|
|
|
## The Solution
|
|
|
|
### Working Docker Compose Configuration
|
|
```yaml
|
|
services:
|
|
server:
|
|
image: gitea/gitea:latest
|
|
container_name: gitea
|
|
environment:
|
|
- USER_UID=1000
|
|
- USER_GID=1000
|
|
- GITEA__server__ROOT_URL=https://ak-homelab.duckdns.org/gitea/
|
|
- GITEA__server__SSH_PORT=2223
|
|
restart: unless-stopped
|
|
|
|
# DO NOT set user: directive - breaks s6-overlay init system
|
|
|
|
ports:
|
|
- "127.0.0.1:3000:3000" # Web UI - localhost only (reverse proxy)
|
|
- "2223:22" # SSH - all interfaces (direct Git access)
|
|
|
|
# Reasonable resource limits only
|
|
deploy:
|
|
resources:
|
|
limits:
|
|
memory: 1G
|
|
```
|
|
|
|
### Key Configuration Points
|
|
|
|
1. **No Docker User Directive**: Let s6-overlay handle user switching via `USER_UID`/`USER_GID`
|
|
2. **ROOT_URL**: Required for asset serving through reverse proxy
|
|
3. **SSH_PORT**: Must match external port for correct clone URLs
|
|
4. **Port Binding**: SSH needs all interfaces, web UI can be localhost-only
|
|
|
|
## Critical Port Configuration
|
|
- **Web UI**: `"127.0.0.1:3000:3000"` (through nginx reverse proxy)
|
|
- **SSH Git**: `"2223:22"` (direct access, NOT localhost-only)
|
|
|
|
**Why SSH can't be localhost-only**: Git operations come from external router/clients and need direct container access.
|
|
|
|
## Asset Loading Fix
|
|
Added `GITEA__server__ROOT_URL=https://ak-homelab.duckdns.org/gitea/` so Gitea serves assets with correct paths through reverse proxy.
|
|
|
|
## Repository Migration
|
|
For fresh Gitea instances, bare repositories must be pushed via Git protocol:
|
|
```bash
|
|
git clone /path/to/bare/repo.git working-copy
|
|
cd working-copy
|
|
git remote set-url origin https://ak-homelab.duckdns.org/gitea/user/repo.git
|
|
git push -u origin --all
|
|
git push origin --tags
|
|
```
|
|
|
|
## Lessons Learned
|
|
1. **Understand service requirements** before applying security hardening
|
|
2. **Some services need specific initialization processes** (s6-overlay)
|
|
3. **Network access patterns matter** (SSH vs HTTP proxy requirements)
|
|
4. **Test incrementally** rather than applying multiple security changes at once
|