pixie / docs
SOURCE GUIDE GitHub ↗
User guide

Choose your deployment.

Start locally, run a container, or use the Linux and Kubernetes packaging in this repository.

Docker

Docker is the shortest path to the sample site. The image is published for amd64 and arm64.

docker run --rm -p 8080:8080 ghcr.io/laflut3/pixie:latest

From a repository checkout, build the current source or use Compose:

docker build -f infrastructure/docker/Dockerfile -t pixie:local .
docker run --rm -p 8080:8080 pixie:local

# Or use the published image through Compose
docker compose -f infrastructure/docker/compose.yaml up -d

Compose mounts infrastructure/config/config-pixie.yml. Stop it with docker compose -f infrastructure/docker/compose.yaml down.

Local Cargo build

Run these commands in the repository root with the Rust toolchain required by Cargo.toml.

PIXIE_CONFIG=infrastructure/config/config-pixie.yml cargo run --locked

The supplied config listens on 0.0.0.0:8080. The repository's web/ supplies the pages.

Debian / Ubuntu and Arch Linux

The Debian/Ubuntu installer configures the signed APT repository. It supports amd64 and arm64. Review the installer before running it:

curl -fsSLo install-pixie.sh https://raw.githubusercontent.com/laflut3/Pixie/main/infrastructure/apt/install.sh
less install-pixie.sh
bash install-pixie.sh
sudo systemctl enable --now pixie

On Arch Linux, use the AUR package (x86_64 or aarch64):

yay -S pixie-git
sudo systemctl enable --now pixie

To build a Debian package locally:

infrastructure/scripts/build-deb.sh
sudo apt install ./pixie_*.deb
sudo systemctl enable --now pixie

For service logs, use journalctl -u pixie -f. Packaged configuration lives in /etc/pixie/config-pixie.yml.

Kubernetes with Helm

helm upgrade --install pixie infrastructure/helm/pixie \
  --namespace pixie --create-namespace
kubectl -n pixie port-forward service/pixie-pixie 8080:8080

The chart exposes a ClusterIP service. Add your own Ingress or Gateway for external traffic. Its values cover the address, workers, image, service, and resources. Set tls.enabled=true and tls.secretName to mount a Kubernetes TLS Secret. HTTP/3 also requires TLS and http3.enabled=true, which exposes the configured UDP port.

Check your endpoint

curl -i http://localhost:8080/
curl -I http://localhost:8080/
curl -i http://localhost:8080/missing

Expect 200 for the home page and 404 for a missing page. See configuration before changing the listen port, and TLS & mTLS before exposing HTTPS.

Pixie documentation Built from the source. Updated with the features.