---
title: "Server Configs Overview"
description: "Centralized system for version-controlling, syncing, and deploying Docker Compose files and VM/LXC configurations across all homelab hosts. Includes host inventory, sync-configs.sh usage, and secrets management."
type: reference
domain: server-configs
tags: [infrastructure, docker-compose, sync, deployment, homelab]
---

# Home Lab Server Configurations

Version-controlled configuration files for the home lab infrastructure. This system provides a centralized way to track, sync, and deploy Docker Compose files and VM/LXC configurations across multiple hosts.

## Quick Start

```bash
# Check status of all hosts
./sync-configs.sh status

# Pull latest configs from all hosts
./sync-configs.sh pull

# Pull from a specific host
./sync-configs.sh pull ubuntu-manticore

# Show differences between local and remote
./sync-configs.sh diff

# Push configs (no restart)
./sync-configs.sh push

# Deploy and restart a specific service
./sync-configs.sh deploy sba-bots paper-dynasty
```

## Directory Structure

```
server-configs/
├── hosts.yml              # Host inventory with connection details
├── sync-configs.sh        # Main sync script
├── .gitignore             # Prevents secrets from being committed
├── README.md              # This file
│
├── proxmox/               # Proxmox hypervisor configs
│   ├── lxc/               # LXC container configurations
│   └── qemu/              # VM configurations
│
├── ubuntu-manticore/      # Physical Ubuntu server
│   └── docker-compose/
│       ├── jellyfin/
│       ├── tdarr/
│       └── watchstate/
│
├── sba-bots/              # SBA Discord bots VM
│   └── docker-compose/
│       ├── paper-dynasty/
│       ├── major-domo/
│       └── ...
│
├── strat-database/        # Database services VM
│   └── docker-compose/
│       ├── pd-database/
│       ├── sba-database/
│       └── ...
│
├── arr-stack/             # Media automation LXC
│   └── docker-compose/
│       └── arr-stack/
│
├── n8n/                   # Workflow automation LXC
│   └── docker-compose/
│       └── n8n/
│
├── uptime-kuma/           # Service uptime monitoring LXC
│   └── docker-compose/
│       └── uptime-kuma/
│
├── akamai/                # Cloud server (Linode)
│   └── docker-compose/
│       ├── nginx-proxy-manager/
│       ├── major-domo/
│       └── ...
│
└── nobara-desktop/        # Local dev machine
    └── docker-compose/
```

## Host Inventory

| Host | Type | IP | Description |
|------|------|-----|-------------|
| proxmox | Proxmox VE | 10.10.0.11 | Main hypervisor (VMs/LXCs) |
| ubuntu-manticore | Docker | 10.10.0.226 | Physical server - media services |
| discord-bots | Docker | 10.10.0.33 | Discord bots and game services |
| sba-bots | Docker | 10.10.0.88 | SBA/Paper Dynasty production |
| strat-database | Docker | 10.10.0.42 | Database services |
| arr-stack | Docker | 10.10.0.221 | Sonarr/Radarr/etc. |
| n8n | Docker | 10.10.0.210 | Workflow automation |
| gitea | LXC | 10.10.0.225 | Self-hosted Git server + CI/CD |
| uptime-kuma | Docker | 10.10.0.227 | Service uptime monitoring |
| akamai | Docker | 172.237.147.99 | Public-facing services |
| nobara-desktop | Local | - | Development workstation |

## Commands Reference

### `./sync-configs.sh pull [host]`
Pulls Docker Compose files from remote hosts to the local repository. Only syncs `docker-compose*.yml`, `compose.yml`, and `.env.example` files - not application data.

### `./sync-configs.sh push [host]`
Pushes local configs to remote hosts. Does NOT restart services. Use this to stage changes before deployment.

### `./sync-configs.sh diff [host]`
Shows differences between local repository and remote host configurations.

### `./sync-configs.sh deploy <host> <service>`
Pushes config for a specific service and restarts it. Example:
```bash
./sync-configs.sh deploy sba-bots paper-dynasty
```

### `./sync-configs.sh status`
Shows connectivity status and config count for all hosts.

### `./sync-configs.sh list`
Lists all configured hosts and their services.

## Secrets Management

**Secrets are NOT stored in this repository.**

All sensitive values (tokens, passwords, API keys) are referenced via environment variables (`${VAR_NAME}`) and stored in `.env` files on each host. The `.gitignore` prevents `.env` files from being committed.

For each service that requires secrets, a `.env.example` file is provided showing the required variables:

```bash
# Example .env.example
BOT_TOKEN=your_discord_bot_token_here
API_TOKEN=your_api_token_here
DB_PASSWORD=your_database_password_here
```

When deploying a new service:
1. Copy `.env.example` to `.env` on the target host
2. Fill in the actual secret values
3. Run `docker compose up -d`

## Workflow

### Making Configuration Changes

1. **Pull latest** to ensure you have current configs:
   ```bash
   ./sync-configs.sh pull
   ```

2. **Edit locally** in your preferred editor

3. **Review changes** before pushing:
   ```bash
   ./sync-configs.sh diff <host>
   ```

4. **Push changes** to the host:
   ```bash
   ./sync-configs.sh push <host>
   ```

5. **Deploy** when ready to restart:
   ```bash
   ./sync-configs.sh deploy <host> <service>
   ```

6. **Commit** to git:
   ```bash
   git add -A && git commit -m "Update <service> config"
   ```

### Adding a New Host

1. Add host entry to `hosts.yml`:
   ```yaml
   new-host:
     type: docker
     ssh_alias: new-host
     ip: 10.10.0.XXX
     user: cal
     description: "Description here"
     config_paths:
       docker-compose: /path/to/compose/files
     services:
       - service1
       - service2
   ```

2. Add SSH alias to `~/.ssh/config` if needed

3. Create directory and pull:
   ```bash
   mkdir -p server-configs/new-host/docker-compose
   ./sync-configs.sh pull new-host
   ```

### Adding a New Service

1. Create the service on the host with `docker-compose.yml`
2. Pull the config:
   ```bash
   ./sync-configs.sh pull <host>
   ```
3. Sanitize any hardcoded secrets (replace with `${VAR}` references)
4. Create `.env.example` if secrets are required
5. Commit to git

## Proxmox Configs

Proxmox VM and LXC configurations are pulled for reference and backup purposes. The sync script does NOT push Proxmox configs back automatically due to the sensitive nature of hypervisor configuration.

To restore a VM/LXC config:
1. Review the config file in `proxmox/qemu/` or `proxmox/lxc/`
2. Manually copy to Proxmox if needed
3. Use Proxmox web UI or CLI for actual restoration

## Troubleshooting

### Host shows as offline
- Check if the VM/LXC is running on Proxmox
- Verify SSH connectivity: `ssh <host-alias>`
- Check `hosts.yml` for correct IP/alias

### Changes not taking effect
- Ensure you ran `push` after editing
- Check if service needs restart: `deploy` command
- Verify the remote file was updated: `diff` command

### Permission denied on push
- Check SSH key is loaded: `ssh-add -l`
- Verify user has write access to config directory
- For root-owned paths (arr-stack, n8n), ensure SSH alias uses correct user

## Related Documentation

- [Tdarr Setup](../tdarr/CONTEXT.md) - Media transcoding configuration
- [Networking](../networking/CONTEXT.md) - NPM and network config
- [Monitoring](../monitoring/CONTEXT.md) - System monitoring setup
- [Gitea CI/CD](gitea/INDEX.md) - Gitea Actions and workflow templates
