klammertext/doc/install/linux_container_install.md

# Running Klammertext on Linux with Docker

This guide runs Klammertext on a Linux system (Ubuntu or Pop!_OS — the steps are
identical) using the prebuilt Docker container. You do **not** need to install
TeX Live, Python, or any programming tools — everything, including the TeX Live
system that makes PDFs, is packaged inside a single downloadable image. You
install Docker once, then Klammertext works like a normal command.

The published image is multi-arch, so Docker pulls the build matching your CPU
(`amd64` on Intel/AMD, `arm64` on ARM machines) automatically.

For a source build instead (full `@eval` access, no Docker), see
`linux_source_install.md`.

## Step 1 — Install Docker

```bash
sudo apt-get update
sudo apt-get install docker.io
sudo usermod -aG docker $USER
```

Log out and back in for the group change to take effect (so you can run `docker`
without `sudo`). You only do this once.

## Step 2 — Download Klammertext

```bash
docker pull akopra/klammertext:latest
```

This downloads Klammertext and its built-in TeX Live (a few hundred megabytes).
You won't need to do it again unless you're updating.

## Step 3 — Add the Klammertext commands

Add these aliases to `~/.bashrc` (or `~/.zshrc`) so `ktext`, `kdesc`, and
`kdiag` work as ordinary commands that read and write files in whatever folder
you run them from:

```bash
alias ktext='docker run --rm -u $(id -u):$(id -g) -v "$PWD:/work" -w /work akopra/klammertext ktext'
alias kdesc='docker run --rm -v "$PWD:/work" -w /work akopra/klammertext kdesc'
alias kdiag='docker run --rm -v "$PWD:/work" -w /work akopra/klammertext kdiag'
```

The `-u $(id -u):$(id -g)` on `ktext` makes output files owned by you rather than
root. `kdesc` and `kdiag` only read files, so they don't need it. The
`-v "$PWD:/work"` mounts your current directory into the container as `/work`,
which is required for the commands to see your files.

Reload your shell (open a new terminal, or `source ~/.bashrc`).

## Step 4 — Make your first document

In a folder you want to work in, create a test file:

```bash
cat > hello.kt <<'EOF'
@document
:structure article
:title Hello
:text
@s1 Hello, Klammertext @

This document was produced with no TeX Live installed — just Docker and the
Klammertext image.
@
EOF
```

Produce a web page and a PDF:

```bash
ktext hello.kt -t html     # makes hello/index.html
ktext hello.kt -t pdf      # makes hello.pdf
```

That's it — you're running Klammertext.

## Updating

To update to the latest published image:

```bash
docker pull akopra/klammertext:latest
```

## Haskell support (`@eval :haskell`)

The standard image does not include Haskell. For `@eval :haskell`, pull the
Haskell image and use it in place of the standard one:

```bash
docker pull akopra/klammertext:haskell
alias ktext='docker run --rm -u $(id -u):$(id -g) -v "$PWD:/work" -w /work akopra/klammertext:haskell ktext'
```

Test:

```bash
ktext -s '@eval :haskell main = putStrLn "hello" @' -d
```

Alternatively, a source install gives all `@eval` modes without a separate image
(see `linux_source_install.md`).

## Klammer set loading

The Standard Klammer Set is loaded by default. To load a different klammer set,
pass `-k PATH` (the klammer set's `.k` file). To run with only the three
primitive klammers (`@read`, `@eval`, `@cond`), use `-k none`.

## If something goes wrong

- **`Cannot connect to the Docker daemon`** — the Docker service isn't running:
  `sudo systemctl start docker`, then retry.
- **`permission denied` running `docker`** — your user isn't in the `docker`
  group yet: `sudo usermod -aG docker $USER`, then log out and back in.
- **`No such file or directory` for your input** — the file must be in the
  directory you run the command from (that's what gets mounted). `cd` into the
  folder with your `.kt` files first.
- **Output files owned by root** — add `-u $(id -u):$(id -g)` to the `ktext`
  command/alias (as shown in Step 3).

## Freeing disk space

To remove the image (you can re-pull it later):

```bash
docker rmi akopra/klammertext:latest
docker system prune          # optional: remove all unused Docker data
```