Skip to content
Raddex

Quick start

This guide gets a local HTTP service behind Raddex without requiring a public domain or privileged ports. It uses one terminal for the upstream and one for Raddex.

1. Start an upstream

Section titled “1. Start an upstream”

If you do not already have a service on 127.0.0.1:8080, run:

Terminal window
python3 -m http.server 8080 --bind 127.0.0.1

Keep that terminal open.

2. Write a Raddexfile

Section titled “2. Write a Raddexfile”

Create Raddexfile:

example.local:8090 {
    reverse_proxy 127.0.0.1:8080
}

The explicit port keeps this example on plain HTTP. A named site without a port uses port 443 and enters the automatic HTTPS path, which is covered in Sites, ports, and HTTPS.

3. Validate before starting

Section titled “3. Validate before starting”
Terminal window
raddex check -c Raddexfile

The command must exit with status 0 and print:

Raddexfile: ok

The same validation is used by a reload, so this is the right check for CI and deployment scripts.

4. Run and send a request

Section titled “4. Run and send a request”

Start Raddex in a second terminal:

Terminal window
raddex run -c Raddexfile

Then send a request with the site Host header:

Terminal window
curl -H 'Host: example.local' http://127.0.0.1:8090/

The Host header matters because Raddex selects an HTTP site per listener. These two requests deliberately exercise the fixed fallbacks:

Terminal window
curl http://127.0.0.1:8090/                             # 400: missing Host
curl -H 'Host: unknown.example' http://127.0.0.1:8090/  # 404: no matching site

Add a second site

Section titled “Add a second site”

A listener can serve multiple named sites:

example.local:8090 {
    reverse_proxy 127.0.0.1:8080
}


static.local:8090 {
    root ./public
    file_server
}

Create a file and restart Raddex with the updated configuration:

Terminal window
mkdir -p public
printf '%s\n' 'hello from raddex' > public/hello.txt
raddex check -c Raddexfile

Fetch it through the second site:

Terminal window
curl -H 'Host: static.local' http://127.0.0.1:8090/hello.txt

For a running service, send SIGHUP instead of restarting. The routing snapshot is replaced atomically and existing connections remain open:

Terminal window
kill -HUP <raddex-pid>

Try HTTPS locally

Section titled “Try HTTPS locally”

Use an internal certificate when you do not have a public ACME domain:

dev.local:8443 {
    tls internal
    reverse_proxy 127.0.0.1:8080
}
Terminal window
raddex check -c Raddexfile
raddex run -c Raddexfile
curl -k -H 'Host: dev.local' https://127.0.0.1:8443/

tls internal is intended for development or private trust domains. For a public site, see HTTPS and TLS.

Next steps

Section titled “Next steps”