# Installation

Muximux is distributed as a single binary with the frontend embedded. There is nothing else to install -- no database, no external dependencies, no separate web server. Choose whichever installation method suits your setup.

---

## Docker (Recommended)

The Docker image is the simplest way to run Muximux. It is published to the GitHub Container Registry.

```bash
mkdir -p data
docker run -d \
  --name muximux \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  --restart unless-stopped \
  ghcr.io/mescon/muximux:latest
```

Then open `http://your-server:8080` in your browser.

### What the volume mount does

The `-v $(pwd)/data:/app/data` flag maps a local `data/` directory into the container at `/app/data`. This is where Muximux stores all persistent state:

- **config.yaml** -- your main configuration file (created automatically on first run)
- **themes/** -- user-created custom CSS theme files
- **icons/** -- cached and uploaded icons

Without this volume mount, your configuration would be lost every time the container is recreated.

### Environment variables

| Variable | Description |
|----------|-------------|
| `MUXIMUX_DATA` | Base data directory (default: `data`). In Docker, the CMD sets this to `/app/data`. |
| `MUXIMUX_CONFIG` | Override config file path (default: derived from data dir as `<data>/config.yaml`). |
| `MUXIMUX_LISTEN` | Override listen address (e.g., `:9090`). |
| `TZ` | Timezone (e.g., `America/New_York`, `Europe/London`). Defaults to `UTC`. |

---

## Docker Compose

For a more declarative setup, use Docker Compose.

```yaml
services:
  muximux:
    image: ghcr.io/mescon/muximux:latest
    container_name: muximux
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=UTC
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
```

Start it with:

```bash
docker compose up -d
```

---

## Binary

Download a pre-built binary from the [Releases](https://github.com/mescon/Muximux/releases) page, or build from source (see below).

Run it directly:

```bash
./muximux
```

By default, Muximux uses `data/` beside the binary as its base data directory, which contains `config.yaml`, themes, and icon caches. If the config file does not exist, Muximux starts with default settings and no apps configured.

### Command-line flags

| Flag | Default | Description |
|------|---------|-------------|
| `--data` | `data/` beside binary | Base data directory for config, themes, and icons (env: `MUXIMUX_DATA`) |
| `--config` | *(derived from data dir)* | Override config file path (env: `MUXIMUX_CONFIG`). Defaults to `<data>/config.yaml`. |
| `--listen` | from config | Override listen address (env: `MUXIMUX_LISTEN`) |
| `--base-path` | *(empty)* | Base URL path for reverse proxy subpath, e.g. `/muximux` (env: `MUXIMUX_BASE_PATH`) |
| `--version` | | Print version information and exit |

---

## Verifying a Download

Every release binary and container image published from 3.3.2 onward carries
a signed [SLSA provenance](https://slsa.dev/provenance/v1) attestation binding
it to the exact workflow, repository and tag that produced it. The signing key
is ephemeral and never stored -- GitHub's OIDC token binds the certificate to
the individual workflow run.

Verification needs the [GitHub CLI](https://cli.github.com/) and no other setup.

### Binaries

```bash
gh attestation verify muximux-linux-amd64 \
  --repo mescon/Muximux \
  --signer-workflow mescon/Muximux/.github/workflows/release.yml
```

### Container images

```bash
gh attestation verify oci://ghcr.io/mescon/muximux:3.3.2 \
  --repo mescon/Muximux \
  --signer-workflow mescon/Muximux/.github/workflows/release.yml
```

An exit status of `0` means the artifact verified; recent `gh` versions print
nothing on success. A failure exits non-zero and says why.

**Prefer `--signer-workflow` over bare `--repo`.** On its own, `--repo` only
asserts that *some* workflow in the repository signed the artifact. Naming the
workflow asserts *which* one, so a build produced by any other workflow in the
repo -- including one added by a compromised or mistaken change -- fails the
check rather than passing it.

### Checksums

`checksums.txt` accompanies every release and covers the binaries and the SBOM:

```bash
sha256sum -c checksums.txt
```

Checksums confirm the file is intact; the attestation confirms *where it came
from*. They answer different questions, so use both.

### SBOM

`muximux-sbom.spdx.json` is an SPDX 2.3 software bill of materials for the
release. It lets you answer "is this build affected by CVE-X" without
rebuilding, and can be fed straight to a scanner:

```bash
grype sbom:muximux-sbom.spdx.json
```

---

## Building from Source

Building from source requires:

- **Go 1.26** or newer
- **Node.js 20** or newer (with npm)

```bash
git clone https://github.com/mescon/Muximux.git
cd Muximux

# 1. Build the frontend
cd web
npm install
npm run build
cd ..

# 2. Build the binary (the frontend is embedded at compile time)
go build -tags embed_web -o muximux ./cmd/muximux

# 3. Run (uses data/ directory by default)
./muximux
```

The `npm run build` step compiles the Svelte frontend and outputs it to `internal/server/dist/`. The `go build -tags embed_web` step then embeds those files into the Go binary. The `-tags embed_web` flag is required -- without it, the binary will not include the web UI. The result is a single, self-contained executable.

> **Note:** There is no Makefile. The two-step build (frontend, then backend) is all that is needed.

---

## Data Directory Structure

Whether you use Docker or run the binary directly, Muximux stores all mutable data (config, themes, icon caches) in a single directory. In Docker, this is `/app/data` (mapped via volume). When running the binary, this defaults to `data/` relative to the binary's location (not the working directory). You can change it with `--data` or the `MUXIMUX_DATA` environment variable.

```
data/
  config.yaml              Main configuration file
  themes/                  User-created custom CSS themes
  icons/
    dashboard/             Cached icons from Dashboard Icons
    lucide/                Cached Lucide icon SVGs
    custom/                User-uploaded icon files
```

### config.yaml

The main configuration file. Contains all settings: server, authentication, navigation, apps, groups, health monitoring, keyboard shortcuts, and icon settings. See the [Configuration Reference](configuration.md) for the full format.

If this file does not exist when Muximux starts, defaults are used and the onboarding wizard is shown on first visit.

### themes/

Custom CSS theme files created through the Settings UI or placed here manually. The built-in Muximux palette (theme ids `muximux` and `muximux-light`) and the bundled third-party themes (Catppuccin, Nord, Dracula, etc.) are compiled into the binary and do not appear in this directory.

### icons/dashboard/

Locally cached copies of icons fetched from the [Dashboard Icons](https://github.com/homarr-labs/dashboard-icons) project. These are downloaded on demand and cached according to the configured TTL (default: 7 days).

### icons/lucide/

Cached SVGs from the [Lucide](https://lucide.dev/) icon set, used for group icons and other UI elements.

### icons/custom/

Icons uploaded by the user through the Settings UI. These can be PNG, SVG, or any other image format.