mirror of
https://github.com/basnijholt/compose-farm.git
synced 2026-02-03 14:13:26 +00:00
1e3b1d71ed
* config: Add local_host and web_stack options Allow configuring local_host and web_stack in compose-farm.yaml instead of requiring environment variables. This makes it easier to deploy the web UI with just a config file mount. - local_host: specifies which host is "local" for Glances connectivity - web_stack: identifies the web UI stack for self-update detection Environment variables (CF_LOCAL_HOST, CF_WEB_STACK) still work as fallback for backwards compatibility. Closes #152 * docs: Clarify glances_stack is used by CLI and web UI * config: Env vars override config, add docs - Change precedence: environment variables now override config values (follows 12-factor app pattern) - Document all CF_* environment variables in configuration.md - Update example-config.yaml to mention env var overrides * config: Consolidate env vars, prefer config options - Update docker-compose.yml to comment out CF_WEB_STACK and CF_LOCAL_HOST (now prefer setting in compose-farm.yaml) - Update init-env to comment out CF_LOCAL_HOST (can be set in config) - Update docker-deployment.md with new "Config option" column - Simplify troubleshooting to prefer config over env vars * config: Generate CF_LOCAL_HOST with config alternative note Instead of commenting out CF_LOCAL_HOST, generate it normally but add a note in the comment that it can also be set as 'local_host' in config. * config: Extend local_host to all web UI operations When running the web UI in a Docker container, is_local() can't detect which host the container is on due to different network namespaces. Previously local_host/CF_LOCAL_HOST only affected Glances connectivity. Now it also affects: - Container exec/shell (runs locally instead of via SSH) - File editing (uses local filesystem instead of SSH) Added is_local_host() helper that checks CF_LOCAL_HOST/config.local_host first, then falls back to is_local() detection. * refactor: DRY get_web_stack helper, add tests - Move get_web_stack to deps.py to avoid duplication in streaming.py and actions.py - Add tests for config.local_host and config.web_stack parsing - Add tests for is_local_host, get_web_stack, and get_local_host helpers - Tests verify env var precedence over config values * glances: rely on CF_WEB_STACK for container mode Restore docker-compose env defaults and document local_host scope. * web: ignore local_host outside container Document container-only behavior and adjust tests. * web: infer local host from web_stack Drop local_host config option and update docs/tests. * Remove CF_LOCAL_HOST override * refactor: move web_stack helpers to Config class - Add get_web_stack() and get_local_host_from_web_stack() as Config methods - Remove duplicate _get_local_host_from_web_stack() from glances.py and deps.py - Update deps.py get_web_stack() to delegate to Config method - Add comprehensive tests for the new Config methods * config: remove web_stack config option The web_stack config option was redundant since: - In Docker, CF_WEB_STACK env var is always set - Outside Docker, the container-specific behavior is disabled anyway Simplify by only using the CF_WEB_STACK environment variable. * refactor: remove get_web_stack wrapper from deps Callers now use config.get_web_stack() directly instead of going through a pointless wrapper function. * prompts: add rule to identify pointless wrapper functions
102 lines
2.5 KiB
Markdown
102 lines
2.5 KiB
Markdown
---
|
|
icon: lucide/container
|
|
---
|
|
|
|
# Docker Deployment
|
|
|
|
Run the Compose Farm web UI in Docker.
|
|
|
|
## Quick Start
|
|
|
|
**1. Get the compose file:**
|
|
|
|
```bash
|
|
curl -O https://raw.githubusercontent.com/basnijholt/compose-farm/main/docker-compose.yml
|
|
```
|
|
|
|
**2. Generate `.env` file:**
|
|
|
|
```bash
|
|
cf config init-env
|
|
```
|
|
|
|
This auto-detects settings from your `compose-farm.yaml`:
|
|
- `DOMAIN` from existing traefik labels
|
|
- `CF_COMPOSE_DIR` from config
|
|
- `CF_UID/GID/HOME/USER` from current user
|
|
|
|
Review the output and edit if needed.
|
|
|
|
**3. Set up SSH keys:**
|
|
|
|
```bash
|
|
docker compose run --rm cf ssh setup
|
|
```
|
|
|
|
**4. Start the web UI:**
|
|
|
|
```bash
|
|
docker compose up -d web
|
|
```
|
|
|
|
Open `http://localhost:9000` (or `https://compose-farm.example.com` if using Traefik).
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
The `cf config init-env` command auto-detects most settings. After running it, review the generated `.env` file and edit if needed:
|
|
|
|
```bash
|
|
$EDITOR .env
|
|
```
|
|
|
|
### What init-env detects
|
|
|
|
| Variable | How it's detected |
|
|
|----------|-------------------|
|
|
| `DOMAIN` | Extracted from traefik labels in your stacks |
|
|
| `CF_COMPOSE_DIR` | From `compose_dir` in your config |
|
|
| `CF_UID/GID/HOME/USER` | From current user (for NFS compatibility) |
|
|
|
|
If auto-detection fails for any value, edit the `.env` file manually.
|
|
|
|
### Glances Monitoring
|
|
|
|
To show host CPU/memory stats in the dashboard, deploy [Glances](https://nicolargo.github.io/glances/) on your hosts. When running the web UI container, Compose Farm infers the local host from `CF_WEB_STACK` and uses the Glances container name for that host.
|
|
|
|
See [Host Resource Monitoring](https://github.com/basnijholt/compose-farm#host-resource-monitoring-glances) in the README.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### SSH "Permission denied" or "Host key verification failed"
|
|
|
|
Regenerate keys:
|
|
|
|
```bash
|
|
docker compose run --rm cf ssh setup
|
|
```
|
|
|
|
### Files created as root
|
|
|
|
Add the non-root variables above and restart.
|
|
|
|
---
|
|
|
|
## All Environment Variables
|
|
|
|
For advanced users, here's the complete reference:
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `DOMAIN` | Domain for Traefik labels | *(required)* |
|
|
| `CF_COMPOSE_DIR` | Compose files directory | `/opt/stacks` |
|
|
| `CF_UID` / `CF_GID` | User/group ID | `0` (root) |
|
|
| `CF_HOME` | Home directory | `/root` |
|
|
| `CF_USER` | Username for SSH | `root` |
|
|
| `CF_WEB_STACK` | Web UI stack name (enables self-update, local host inference) | *(none)* |
|
|
| `CF_SSH_DIR` | SSH keys directory | `~/.ssh/compose-farm` |
|
|
| `CF_XDG_CONFIG` | Config/backup directory | `~/.config/compose-farm` |
|