mirror of https://github.com/basnijholt/compose-farm.git synced 2026-02-03 06:03:25 +00:00

Files

Bas Nijholt 1e3b1d71ed Drop CF_LOCAL_HOST; limit web-stack inference to containers (#163 )

* 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

2026-01-10 10:48:35 +01:00

2.5 KiB

Raw Permalink Blame History

icon

icon
lucide/container

Docker Deployment

Run the Compose Farm web UI in Docker.

Quick Start

1. Get the compose file:

curl -O https://raw.githubusercontent.com/basnijholt/compose-farm/main/docker-compose.yml

2. Generate .env file:

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:

docker compose run --rm cf ssh setup

4. Start the web UI:

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:

$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 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 in the README.

Troubleshooting

SSH "Permission denied" or "Host key verification failed"

Regenerate keys:

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`

2.5 KiB Raw Permalink Blame History