HaLOS Core Containers

Core container application definitions for HaLOS. These apps are pre-installed in HaLOS images, providing essential system functionality including Single Sign-On (SSO).

What's in This Repository

This repository contains core HaLOS container applications:

• Traefik - Reverse proxy and load balancer, routes all web traffic via subdomains
• Authelia - Identity provider for SSO (OIDC + ForwardAuth)
• Homarr - Dashboard landing page at https://{hostname}.local/

Key difference from halos-marine-containers: No store package - core apps are pre-installed in HaLOS images, not discovered via store UI.

Single Sign-On (SSO)

HaLOS provides unified authentication across all web applications:

• All apps accessible via subdomains: {app}.{hostname}.local
• Single login for all applications
• HTTP automatically redirects to HTTPS
• Three auth modes: ForwardAuth (default), OIDC, or none

See docs/SSO_SPEC.md and docs/SSO_ARCHITECTURE.md for details.

Multi-Hostname Configuration

By default, HaLOS answers to two names:

• ${hostname}.local — mDNS, works on any LAN.
• ${fqdn} — full DHCP/admin domain (e.g., halosdev.example.com when DHCP option 15 is set or the admin runs hostnamectl set-hostname).

Both are listed in the shipped /etc/halos/hostnames.conf. To add VPN aliases or other multi-label DNS names, edit the file:

# /etc/halos/hostnames.conf
${hostname}.local           # canonical (first entry)
${fqdn}                     # auto-resolved DHCP/admin FQDN
halosdev.example.com        # VPN/DNS alias

Single-label hostnames and raw IPs are deliberately not in the example set — they cannot carry an Authelia session cookie (RFC 6265 §5.3 step 5; Authelia 4.39+ rejects them outright), so SSO breaks on them in non-obvious ways. See docs/HOSTNAMES.md for the full token reference, resolver chain, and trust-boundary notes.

After editing, restart the service:

sudo systemctl restart halos-core-containers.service

This drives:

• TLS cert SANs — the self-signed cert covers every entry (DNS and IP)
• Authelia session cookies — one per-DNS-hostname entry; sessions are host-sticky (logging in on hostname A does not authenticate hostname B). IP entries are excluded: RFC 6265 forbids cookies scoped to IP literals, so ForwardAuth cannot work over IP-addressed access.
• OIDC redirect_uris — one entry per DNS hostname (IPs excluded)

IP entries serve a single purpose: they appear as cert SANs so that direct HTTPS access to the device (e.g., Cockpit at https://<IP>:9090/, which has its own authentication) does not trigger a self-signed-cert warning.

Canonical hostname

The first non-IP entry is canonical. The OIDC issuer URL (the iss claim, the discovery endpoint, NextAuth's NEXTAUTH_URL) always points to the canonical host. OIDC login on a non-canonical hostname briefly visits canonical for the Authelia UI, then returns to the originating host. The canonical host must be reachable from the user's network for OIDC login to succeed.

Cross-paradigm SSO trade-off

Per-hostname session isolation means:

• Cockpit, Grafana, Signal K (ForwardAuth apps) → log in once per hostname you visit.
• Homarr (OIDC app) → SSO works across hostnames because the OIDC flow always runs through canonical.
• Mixed flow: visit Homarr on a non-canonical hostname; the auth round trip seeds a canonical Authelia session. Visiting Cockpit on the same non-canonical hostname will still prompt for login.

Troubleshooting

• Device unreachable on a hostname: check hostnames.conf for typos, verify the hostname resolves from your network, restart the service.

• HALOS_HOSTNAMES_FALLBACK in the journal: the config failed validation and the device booted in single-SAN mode. Inspect the journal message for the cause:

  journalctl -u halos-core-containers.service | grep HALOS_HOSTNAMES_FALLBACK
  

• Stale ${hostname}.local after rename: the ${hostname} token in hostnames.conf re-expands at every prestart, so renaming via hostnamectl set-hostname followed by a service restart is enough. If you pinned a literal hostname instead, edit the file.

Limitations

• Hostnames are admin-managed. There is no Cockpit UI yet.
• The Cockpit :9090 cert is separate and is not regenerated by this config.
• DNS-name aliases must be admin-pruned when ownership changes (stale-alias takeover risk).
• Maximum 16 entries.

Build Output

CI/CD builds Debian packages from this repository:

• halos-traefik-container - Reverse proxy
• halos-authelia-container - SSO identity provider
• halos-homarr-container - Dashboard landing page

All packages are published to apt.hatlabs.fi.

Agentic Coding Setup (Claude Code, GitHub Copilot, etc.)

For development with AI assistants, use the halos workspace for full context:

# Clone the workspace
git clone https://github.com/halos-org/halos.git
cd halos

# Get all sub-repositories including halos-core-containers
./run repos:clone

# Work from workspace root for AI-assisted development
# Claude Code gets full context across all repos

See halos/docs/ for development workflows:

• LIFE_WITH_CLAUDE.md - Quick start guide
• IMPLEMENTATION_CHECKLIST.md - Development checklist
• DEVELOPMENT_WORKFLOW.md - Detailed workflows

Repository Structure

halos-core-containers/
├── apps/
│   ├── traefik/            # Reverse proxy
│   ├── authelia/           # SSO identity provider
│   └── homarr/             # Dashboard landing page
├── docs/
│   ├── SSO_SPEC.md         # SSO technical specification
│   └── SSO_ARCHITECTURE.md # SSO system architecture
├── tools/                   # Build scripts
├── .github/workflows/       # CI/CD
└── README.md

Adding a New App

1. Create apps/<app-name>/ directory
2. Add required files: docker-compose.yml, metadata.yaml, icon.png
3. Optionally add config.yml for user-configurable settings
4. Test locally with container-packaging-tools
5. Create PR - CI will build and validate

Building Locally

Requirements:

• container-packaging-tools package installed

# Build all packages
./tools/build-all.sh

# Build output in build/ directory
ls build/*.deb

Related Repositories

• halos - HaLOS workspace and planning
• halos-marine-containers - Marine container store
• cockpit-apt - APT package manager with store filtering
• container-packaging-tools - Package generation tooling
• apt.hatlabs.fi - APT repository infrastructure

License

Apache License 2.0 - See LICENSE for details.