pixie / docs
SOURCE GUIDE GitHub ↗
User guide

One domain. One site.

Use separate Pixie processes and a front proxy when you need NGINX-style virtual hosting.

How multiple sites work today

Pixie has one web root and one listener per process. It does not select a root from the Host header, provide server blocks, proxy upstreams, or rewrite path prefixes. Run an instance per site on a different local port, then route domains through NGINX.

Browser → NGINX :80 → Pixie :8081 / :8082

Start two instances

Create /srv/pixie/alpha and /srv/pixie/beta, each with hello.html and 404.html. Save two configs:

# /etc/pixie/alpha.yml
addr: 127.0.0.1:8081
workers: 4

# /etc/pixie/beta.yml
addr: 127.0.0.1:8082
workers: 4

Run these in separate terminals for a local demonstration. A production service manager should keep both processes running.

PIXIE_CONFIG=/etc/pixie/alpha.yml PIXIE_WEB_ROOT=/srv/pixie/alpha pixie
# In another terminal:
PIXIE_CONFIG=/etc/pixie/beta.yml PIXIE_WEB_ROOT=/srv/pixie/beta pixie

Route domains with NGINX

After installing NGINX, add these blocks to its site configuration. Replace the example domains and point their DNS records at the host.

server {
    listen 80;
    server_name alpha.example.com;
    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header Host $host;
    }
}

server {
    listen 80;
    server_name beta.example.com;
    location / {
        proxy_pass http://127.0.0.1:8082;
        proxy_set_header Host $host;
    }
}
sudo nginx -t
sudo systemctl reload nginx
curl -H "Host: alpha.example.com" http://127.0.0.1/

This example uses HTTP on the front proxy. Configure its certificates and HTTPS listener for public HTTPS, or configure HTTPS on each Pixie instance as described in TLS & mTLS.

Serve sites under path prefixes

A proxy can strip the prefix before forwarding to the matching instance:

location /alpha/ {
    proxy_pass http://127.0.0.1:8081/;
    proxy_set_header Host $host;
}
location /beta/ {
    proxy_pass http://127.0.0.1:8082/;
    proxy_set_header Host $host;
}

The trailing slash on proxy_pass strips the matched prefix: /alpha/about reaches Pixie as /about. Use prefix-aware or relative links in your HTML. General asset serving remains outside the current Pixie router.

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