https://github.com/halos-org/halos-core-containers
Core container application definitions for HaLOS
https://github.com/halos-org/halos-core-containers
apt-package halos
Last synced: about 1 month ago
JSON representation
Core container application definitions for HaLOS
- Host: GitHub
- URL: https://github.com/halos-org/halos-core-containers
- Owner: halos-org
- License: apache-2.0
- Created: 2025-12-08T19:03:46.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-05-26T11:38:26.000Z (about 1 month ago)
- Last Synced: 2026-05-26T13:32:57.009Z (about 1 month ago)
- Topics: apt-package, halos
- Language: Shell
- Homepage:
- Size: 461 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 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](docs/SSO_SPEC.md) and [docs/SSO_ARCHITECTURE.md](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](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://: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:
```bash
# 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//` 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
```bash
# Build all packages
./tools/build-all.sh
# Build output in build/ directory
ls build/*.deb
```
## Related Repositories
- [halos](https://github.com/halos-org/halos) - HaLOS workspace and planning
- [halos-marine-containers](https://github.com/halos-org/halos-marine-containers) - Marine container store
- [cockpit-apt](https://github.com/halos-org/cockpit-apt) - APT package manager with store filtering
- [container-packaging-tools](https://github.com/halos-org/container-packaging-tools) - Package generation tooling
- [apt.hatlabs.fi](https://github.com/hatlabs/apt.hatlabs.fi) - APT repository infrastructure
## License
Apache License 2.0 - See [LICENSE](LICENSE) for details.