composer/README.md

# Docker Compose — Home Server

## Services

| Container | Image | Purpose |
|-----------|-------|---------|
| `duckdns` | `lscr.io/linuxserver/duckdns` | Dynamic DNS — keeps `*.duckdns.org` pointed at the home IP |
| `homeassistant` | `homeassistant/home-assistant` | Home automation, reachable at `:8123` |
| `timemachine` | `mbentley/timemachine:smb` | Time Machine backup server over SMB |
| `samba` | `dperson/samba` | General SMB file share for Mac and Linux clients |
| `forgejo` | `codeberg.org/forgejo/forgejo` | Self-hosted Git server, web UI at `:3000`, SSH at `:2222` |

## Initial Setup

1. Copy and fill in the environment file:

   ```bash
   cp .env.example .env
   nano .env
   ```

2. Create the required host directories if they don't exist:

   ```bash
   mkdir -p /home/padriano/projects/forgejo
   mkdir -p /home/padriano/share
   ```

   The Samba container runs as UID/GID 1001 internally, so the share directory must be owned by that user:

   ```bash
   sudo chown 1001:1001 /home/padriano/share
   ```

3. Bring the full stack up:

   ```bash
   cd /home/padriano/projects/composer
   docker compose up -d
   ```

---

## Common Docker Compose Commands

### Stack management

```bash
# Start all services (detached)
docker compose up -d

# Stop all services (containers remain)
docker compose stop

# Stop and remove all containers (data volumes are preserved)
docker compose down

# Restart all services
docker compose restart

# Restart a single service
docker compose restart homeassistant
```

### Viewing status and logs

```bash
# Show running containers and their status
docker compose ps

# Follow logs for all services
docker compose logs -f

# Follow logs for a single service
docker compose logs -f forgejo

# Show last 50 lines for a service
docker compose logs --tail=50 timemachine
```

### Updating images

```bash
# Pull latest images for all services
docker compose pull

# Pull for a single service
docker compose pull forgejo

# Recreate containers that have a newer image
docker compose up -d --pull always

# Recreate a single service after pulling
docker compose up -d --force-recreate forgejo
```

### Inspecting containers

```bash
# Open a shell inside a running container
docker exec -it homeassistant bash
docker exec -it forgejo sh        # alpine-based, use sh not bash

# Show resource usage (CPU, RAM, network)
docker stats

# Inspect container configuration
docker inspect forgejo
```

---

## Service Notes

### duckdns

- Config stored at `/home/padriano/projects/duckdns/config`
- Uses `network_mode: host` — required for Avahi/mDNS broadcast
- Domains managed: `ha-padriano`, `padrianoha`, `padriano` (all `.duckdns.org`)

### homeassistant

- Config stored at `/home/padriano/projects/ha/config`
- Web UI: `http://server:8123` or `http://ha-padriano.duckdns.org`
- Uses `network_mode: host` for device discovery (mDNS, Zigbee, etc.)
- Has a healthcheck — status shows `(health: starting)` for ~60s on first boot

### timemachine

- Backup data stored at `/home/padriano/backup/timemachine`
- Uses `network_mode: host` and a fixed `hostname: timemachine` — the stable hostname prevents macOS from losing the backup destination after container restarts
- On your Mac: **System Settings → General → Time Machine → Add Backup Disk**

### samba

- Shared directory on the host: `/home/padriano/share` — must be owned by `1001:1001` (the UID/GID the container uses internally); without this, the share mounts on the Mac but files cannot be written
- Uses a macvlan network with static IP `192.168.1.247` — avoids port 445 conflict with the `timemachine` container
- Config stored at `samba/smb.conf`; the `[Share]` section is the only exported share
- Avahi service file at `samba/avahi-smb.service` advertises the share for Finder sidebar discovery (installed to `/etc/avahi/services/samba.service` on the host)
- **Connecting from a Mac**: open Finder → Go → Connect to Server → `smb://192.168.1.247/Share`
- **Connecting from Linux**: `smbclient //192.168.1.247/Share -U samba` or mount with `mount -t cifs //192.168.1.247/Share /mnt/share -o username=samba`
- Username and password are set via `SAMBA_USERNAME` / `SAMBA_PASSWORD` in `.env`

### forgejo

- All data (repos, config, SQLite DB) stored at `/home/padriano/projects/forgejo`
- Backing up this single directory is sufficient for a full restore

#### First-run setup

Visit `http://server:3000` on first start and complete the install wizard:

- **Base URL**: `http://padriano.duckdns.org:3000`
- **SSH domain**: `padriano.duckdns.org`
- **SSH port**: `2222`

#### Access

| Method | Local network | External (via DuckDNS) |
|--------|---------------|------------------------|
| Web UI | `http://server:3000` | `http://padriano.duckdns.org:3000` |
| Git SSH | `ssh://git@server:2222` | `ssh://git@padriano.duckdns.org:2222` |

For external access, forward these ports on your router to `192.168.1.116`:

- TCP `3000` → Forgejo web UI
- TCP `2222` → Forgejo SSH

#### Git remote URL examples

```bash
# Add remote via HTTP
git remote add origin http://padriano.duckdns.org:3000/padriano/my-repo.git

# Add remote via SSH
git remote add origin ssh://git@padriano.duckdns.org:2222/padriano/my-repo.git

# Clone via SSH (local)
git clone ssh://git@server:2222/padriano/my-repo.git
```

---

## Disk Space

```bash
# Free space on the main filesystem
df -h /

# Free space on all mounted filesystems
df -h

# Space used by each service's data directory
du -sh /home/padriano/projects/* /home/padriano/backup/*
```

---

## Data & Backup Summary

| Service | Host path | Notes |
|---------|-----------|-------|
| `duckdns` | `/home/padriano/projects/duckdns/config` | Token cache, not critical |
| `homeassistant` | `/home/padriano/projects/ha/config` | All HA config and automations |
| `timemachine` | `/home/padriano/backup/timemachine` | Mac backup sparsebundles |
| `samba` | `/home/padriano/share` | General file share — back up as needed |
| `forgejo` | `/home/padriano/projects/forgejo` | All repos, DB, config |