# Install SMKV

**Applies to:** public APT baseline 0.1.0-2 on Ubuntu 24.04, x86-64. Newer development features need a separately supplied matching build.

## Choose components

| Package | Install on | Purpose |
| --- | --- | --- |
| `smkv` | Database hosts | Run the database server |
| `smkv-tools` | Operator and application test hosts | Use the data CLI and cluster inspection CLI |
| `smkv-web` | A management host | Serve the browser dashboard |

Components install independently. The Go SDK is a source module, not an operating-system package. Development server packages additionally include `smkv-authority`; development tools include `smkv-backup`. These additions are not in the public baseline.

## Add the signed APT repository

Install prerequisites, then add the repository-scoped key. Do not disable signature verification.

```sh
sudo apt update
sudo apt install ca-certificates curl
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://simplemagicdata.com/apt/simplemagicdata.asc \
  | sudo tee /etc/apt/keyrings/simplemagicdata.asc > /dev/null
sudo chmod 0644 /etc/apt/keyrings/simplemagicdata.asc
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/simplemagicdata.asc] https://simplemagicdata.com/apt noble main" \
  | sudo tee /etc/apt/sources.list.d/simplemagicdata.list
sudo apt update
apt-cache policy smkv smkv-tools smkv-web
```

Signing key fingerprint: `FC2B 7F7D 718B 4FC0 2B04 E07A 66C5 503A 016F EBF1`.

Install the components you need. For a single-host evaluation:

```sh
sudo apt install smkv smkv-tools
```

## Configure before starting

Installation does not enable, start, or restart services. Review `/etc/default/smkv`; its `SMKV_ARGS` field contains a systemd argument list, not shell commands. Defaults listen on loopback, with data in `/var/lib/smkv` and metrics on `127.0.0.1:9108`.

```sh
sudoedit /etc/default/smkv
sudo systemctl enable --now smkv
sudo systemctl status smkv
sudo journalctl -u smkv -n 50 --no-pager
```

The systemd dynamic user may back the data path with `/var/lib/private/smkv`. Do not change ownership blindly. Follow [your first records](quickstart.html) to verify the service.

## Dashboard installation

```sh
sudo apt install smkv-web
sudoedit /etc/default/smkv-web
```

Set `SMKV_WEB_ARGS` to include a reachable sharded-cluster management seed. Then start `smkv-web` explicitly. A standalone node has no cluster management endpoint for this dashboard. See [monitoring](monitoring.html).

## Archives and private release packages

For supplied archives, verify the release's `SHA256SUMS`, extract the required component, and run its binary from `bin/`. Keep data outside release directories. Archives install no service automatically. For supplied Debian packages, use `sudo apt install ./PACKAGE.deb`; review the release's compatibility declaration before upgrading.

Published packages target glibc-based Ubuntu amd64. ARM64, Alpine/musl, and native macOS installation packages are not provided. Source builds require an authorized source checkout and Rust 1.89 or newer; build matching components with `cargo build --release --locked --workspace`.

## Removal and upgrades

Stop the affected service before changing its package and start it explicitly afterward. Debian preserves configuration through conffile handling. Removing a server or web package stops that service; purge removes configuration but preserves database data. Custom systemd overrides take precedence over packaged units. See [operations](operations.html) before rolling upgrades.