Server Infrastructure

Infrastructure configuration for the server, managed directly with Docker Compose and Git.

The repository intentionally keeps application-specific configuration out of the root documentation. Each service should document its own setup inside its directory.

Repository Structure

.
├── README.md
│
├── caddy/
│   ├── docker-compose.yml
│   ├── Caddyfile
│   └── README.md
│
├── <service>/
│   ├── docker-compose.yml
│   └── README.md
│
└── <service>/
    ├── docker-compose.yml
    └── README.md

The root README documents the infrastructure conventions. Individual service directories document the applications themselves.

---

Infrastructure

The server uses:

• Arch Linux
• Docker Engine
• Docker Compose
• Caddy
• Git

Docker Compose is used independently for each service rather than maintaining one large Compose project.

This keeps services isolated and makes it possible to start, stop, update, or troubleshoot them independently.

Shared Docker Network

A shared external Docker network named proxy is used for services that need to communicate with the reverse proxy.

Create it once:

docker network create proxy

Check that it exists:

docker network ls

Because it is an external network, individual Compose projects must not attempt to create or manage it.

Compose configuration

A service that needs to be reachable by the reverse proxy should include:

services:
  app:
    image: example/image:latest
    networks:
      - proxy

networks:
  proxy:
    external: true

The important parts are:

networks:
  - proxy

under the service, and:

networks:
  proxy:
    external: true

at the Compose level.

The service name becomes the hostname available to other containers on the proxy network.

For example, if the service is named app, the reverse proxy can connect to:

app:<container-port>

Do not use the server's LAN IP for communication between containers when both containers are attached to proxy.

Service Ports

A service does not need to publish its application port to the host when it is only accessed through the reverse proxy.

Prefer:

services:
  app:
    image: example/image:latest
    networks:
      - proxy

instead of:

ports:
  - "8080:8080"

when direct LAN access is unnecessary.

The application port only needs to be exposed inside the container/network.

Publish a host port only when the service genuinely needs direct access from outside Docker.

Reverse Proxy Integration

Caddy is the entry point for HTTP/HTTPS services.

The general flow is:

Client
  │
  ▼
Server :80/:443
  │
  ▼
Caddy
  │
  ▼
proxy network
  │
  ▼
service container

When adding a web service:

1. Attach the service to proxy.
2. Determine the application's internal listening port.
3. Add a route to the Caddy configuration.
4. Start the service.
5. Reload Caddy.
6. Test the route.

Example Caddy configuration:

192.168.0.254 {
    handle_path /example/* {
        reverse_proxy app:8080
    }
}

The hostname used by reverse_proxy must match the Compose service name or another resolvable container hostname on the shared network.

Creating a New Service

Create a directory for the service:

mkdir <service>
cd <service>

Create docker-compose.yml.

A basic reverse-proxied service can start with:

services:
  app:
    image: example/image:latest
    restart: unless-stopped
    networks:
      - proxy

networks:
  proxy:
    external: true

Then start it:

docker compose up -d

Check it:

docker compose ps
docker compose logs --tail=100

Verify that it is connected to the shared network:

docker network inspect proxy

After configuring Caddy:

cd ~/caddy
docker compose reload caddy

Compose Conventions

Unless a service requires something different, Compose files should generally follow these conventions.

Restart policy

Use:

restart: unless-stopped

for long-running services.

Named volumes

Use named volumes for persistent application data when appropriate:

services:
  app:
    image: example/image:latest
    volumes:
      - app_data:/data

volumes:
  app_data:

Document important volumes in the service's README.

Environment variables

Prefer an .env file for non-secret configuration when it makes the Compose file easier to maintain:

services:
  app:
    env_file:
      - .env

Do not commit passwords, API keys, tokens, or other secrets to Git.

If a service requires an .env file, provide an .env.example containing the required variable names without real credentials.

Directory Convention

Each service directory should contain everything necessary to understand and operate that service:

service/
├── docker-compose.yml
├── README.md
├── .env.example
└── other configuration files

Do not place application-specific instructions in the root README.

The service README should explain:

• Purpose
• Image/container information
• Required environment variables
• Ports
• Volumes
• Networks
• Reverse proxy configuration
• Access URL/path
• Backup requirements
• Update procedure
• Troubleshooting

Common Commands

Start

docker compose up -d

Stop

docker compose down

Restart

docker compose restart

View status

docker compose ps

Follow logs

docker compose logs -f

View recent logs

docker compose logs --tail=100

Pull newer images

docker compose pull

Update a service

docker compose pull
docker compose up -d

Rebuild

For services that use a local Dockerfile:

docker compose up -d --build

Troubleshooting

Work from the infrastructure layer upward.

Host

systemctl --failed
df -h
free -h

Docker

docker ps
docker info
docker network ls

Service

From the service directory:

docker compose ps
docker compose logs --tail=100

Network

docker network inspect proxy

Confirm that the reverse proxy and target service are both attached to the network.

Reverse proxy

From the reverse proxy directory:

docker compose ps
docker compose logs --tail=100

If a proxy route cannot reach a service, first verify:

1. The service container is running.
2. Both containers are attached to proxy.
3. The Compose service name is correct.
4. The internal application port is correct.
5. The application is actually listening on that port.

Backups

Docker Compose files contain infrastructure configuration, but they do not replace application data backups.

Persistent data should be backed up according to the requirements of each service.

Before removing a Docker volume, inspect it carefully:

docker volume ls
docker volume inspect <volume>

Never assume that deleting a container also deletes its persistent data, or that deleting a volume is safe.

Service-specific backup instructions belong in that service's README.

Git

The repository is used to version-control infrastructure configuration.

Typical workflow:

git status
git add .
git commit -m "Update infrastructure"
git push

Keep secrets out of Git.

Recommended files to exclude include:

.env
*.secret

Use .env.example files to document required configuration without storing credentials.

Design Principles

This infrastructure intentionally avoids unnecessary management layers.

The preferred model is:

Linux
  ↓
Docker
  ↓
Docker Compose
  ↓
Service

with Caddy providing the shared HTTP/HTTPS entry point when required.

Configuration should remain:

• Explicit
• Version controlled
• Reproducible
• Easy to inspect
• Easy to troubleshoot
• Independent between services

When adding infrastructure, prefer the simplest configuration that satisfies the requirement.