Install Svix with Docker and Expose It via Localtonet

What this Svix and Localtonet architecture does

Webhooks let one application notify another application when an event occurs. Operating a webhook delivery system involves more than sending a single HTTP request. The system may need to manage customer endpoints, retry failed deliveries, retain delivery information, isolate customer configurations, and protect security-sensitive data. Svix packages these responsibilities behind an API so an application can submit messages while the webhook service manages delivery.

This tutorial focuses on the open-source Svix server from the official Svix GitHub repository. The server is written in Rust, but Docker users do not need to compile it for the documented Compose workflow. The repository includes a Docker Compose configuration that starts Svix with its supporting services.

PostgreSQL is a required Svix runtime dependency and stores events. Redis is optional depending on the queue and cache configuration selected for the server. Svix specifies Redis 6.2.0 or later when Redis is used. The example Docker Compose deployment starts and configures both PostgreSQL and Redis, but that does not mean every independently designed Svix deployment must use Redis.

Local installation and public reachability are separate concerns. First, Docker must expose a healthy Svix HTTP listener on the host. Only after that local path works should a Localtonet HTTP tunnel point to it. Our Localtonet client establishes an outbound connection to a relay server and provides a public HTTPS address for the configured local IP address and port.

This arrangement is useful when an authorized application outside the local network must call the Svix API. It does not require inbound router port forwarding, firewall changes, a VPN, or a public IP address. The route remains available only while the selected Localtonet client is connected and the tunnel is running.

Understand both directions of webhook traffic

A remote Svix API client and a webhook destination use different network paths. A remote API client needs a route to the self-hosted Svix API if that API is otherwise private. The Localtonet tunnel provides that route in this tutorial.

Svix delivering an outgoing webhook to an ordinary public destination does not inherently require a Localtonet tunnel. That delivery is an outbound request from the Svix host to the destination. The host needs suitable outbound network and DNS access, but the Svix API does not need to be public merely for Svix to call a public webhook endpoint.

A separate connectivity design may be necessary if a webhook destination itself is private. Do not confuse that destination route with the HTTP tunnel used here for remote access to the Svix API.

Repository baseline used by this guide

Repositories change over time, so a tutorial that says only “clone the current branch” cannot guarantee the same Compose file, image references, service names, credentials, ports, or volume definitions. This guide uses Git commit da9b423 as its reproducibility baseline. That commit is associated with the repository tag v2.1.0.

The tag is described by Svix as an SDKs and CLI release rather than a Svix Server release number. We use its commit only to identify a concrete repository state for the included files. Do not infer that v2.1.0 is the installed server image version. The actual server image reference remains whatever the checked-out Compose configuration specifies.

git clone https://github.com/svix/svix-webhooks.git
cd svix-webhooks
git checkout da9b423
git rev-parse HEAD
git status --short --branch

The git rev-parse HEAD output should begin with or resolve to the selected commit. A detached HEAD state is expected when checking out a commit directly. Record the complete hash in your deployment notes. If the checkout fails because the local clone does not yet contain the object, fetch repository tags and history, then repeat the checkout.

git fetch --tags --prune
git checkout da9b423
git rev-parse HEAD

You may intentionally use a newer Svix revision, but inspect its Compose configuration and repeat every verification step in this guide. A newer checkout can legitimately use different service names, image versions, port mappings, settings, or persistence behavior.

General usage guidance is available in the Svix documentation. Endpoint schemas and current client examples are maintained in the Svix API reference. Those two resources have different purposes: the documentation explains concepts and workflows, while the API reference defines application requests.

Validate Docker, Compose, Git, and host access

The Svix repository describes Docker Compose as the easiest deployment alternative because it also boots and configures PostgreSQL and Redis. It assumes Docker Compose v2, which uses the docker compose command rather than the older standalone docker-compose command.

Run the following checks on the machine that will host Svix:

git --version
docker --version
docker compose version
docker info

The first three commands confirm that the required command-line tools are available. docker info also checks whether the current account can communicate with the Docker daemon. If it fails with a permission or connection error, resolve the Docker installation or account permissions before proceeding.

The exact Docker Engine and Compose versions supported by your operating system and selected Svix revision should be checked against their current documentation. For Compose behavior and command details, consult the Docker Compose documentation.

Choose where the Localtonet client will run

The simplest arrangement is to run our Localtonet client on the Docker host. In that layout, a port published on the host loopback interface may be usable as the tunnel target. If the client runs on a different device, that device must be able to reach the Docker host through a LAN address and the published host port.

A loopback address always refers to the machine on which the client process runs. Therefore, 127.0.0.1 is correct only when the Localtonet client and the published Svix listener are reachable through the same host loopback interface.

Plan capacity without inventing universal limits

The available evidence does not establish one universal CPU, memory, or storage minimum for this deployment. Requirements depend on message volume, payload sizes, endpoint count, retention, concurrency, retry activity, database growth, and the wider Docker environment. Observe resource use under a representative workload before treating a development host as production capacity.

Install Svix with Docker Compose

Start from the repository root created in the baseline section. The official Svix instructions run Compose from the server directory.

cd server
docker compose config --services
docker compose config
docker compose up

The foreground docker compose up command is useful for the first start because logs remain visible in the terminal. Watch for image download errors, invalid variables, port conflicts, database initialization failures, or containers that repeatedly stop and restart.

After confirming that startup completes, press Ctrl+C to stop the foreground run. You can then start the same project in detached mode:

docker compose up -d
docker compose ps
docker compose logs --tail=200

docker compose ps reports service state and published ports. docker compose logs --tail=200 collects recent output from the entire project. To continue following logs, use:

docker compose logs -f

Stop following logs with Ctrl+C. That action exits the log viewer but does not stop detached containers.

Inspect the rendered images, ports, and volumes

Do not rely on assumptions about a different Svix release. Use the rendered model to see what this checkout will run:

docker compose config --images
docker compose config --volumes
docker compose ps

You can also inspect the port bindings of every container in the current Compose project without guessing a container name:

docker compose ps -q | xargs -r docker inspect \
  --format '{{.Name}} {{json .NetworkSettings.Ports}}'

On systems whose xargs implementation does not support -r, first confirm that docker compose ps -q returns container IDs, then run the inspection without that option. The output associates each container port with any host address and host port Docker published.

Understand PostgreSQL and optional Redis

PostgreSQL is required for Svix event storage. Redis is optional at the server level and depends on the selected queue and cache configuration. The supplied example Compose workflow includes Redis, which is why three services may appear in this deployment.

When Redis is selected, Svix requires Redis 6.2.0 or later. Svix recommends persistence so queued tasks survive Redis restarts and upgrades. It also advises configuring Redis not to evict keys without explicit expiration policies. The documented choices include noeviction and the available volatile-* policies.

Do not remove Redis from the example stack merely because it is described as optional in the general runtime requirements. First inspect the selected queue type, cache configuration, and Compose environment. Optional means the server supports configurations without Redis, not that Redis can be removed from a Redis-based configuration without replacing those settings.

Standalone Docker is an advanced alternative

Svix also documents running the official image as a standalone container:

docker run \
  --name svix-server \
  -p 8071:8071 \
  --env-file development.env \
  svix/svix-server

This command maps host port 8071 to container port 8071. It does not install PostgreSQL or Redis in the same container. You must always provide a working PostgreSQL connection. You provide Redis 6.2.0 or later only when your selected queue or cache configuration uses Redis.

Svix supports environment variables, a .env file, and a TOML configuration file. A file named config.toml in the server’s current working directory is detected automatically. Equivalent environment variables use uppercase configuration names with an SVIX_ prefix.

A structural environment file could contain the following placeholders, but it is not a ready-to-run configuration:

SVIX_JWT_SECRET=<securely-generated-private-secret>
SVIX_DB_DSN=<postgresql-connection-string>
SVIX_REDIS_DSN=<redis-connection-string-if-used>
SVIX_QUEUE_TYPE=<selected-queue-type>

Verify Svix locally before creating a tunnel

A complete check distinguishes infrastructure health, HTTP reachability, and authenticated Svix behavior. An HTTP response can prove that a listener answered without proving that credentials, API paths, or application data are correct.

Run the container checks from the repository’s server directory:

docker compose ps
docker compose logs --tail=200
docker compose ps -q | xargs -r docker inspect \
  --format '{{.Name}} {{json .NetworkSettings.Ports}}'

Suppose the inspection shows that the Svix container’s port is published on host port 8071. Set a shell variable to the exact address reachable from the machine that will run the Localtonet client:

SVIX_LOCAL_URL="http://127.0.0.1:8071"
printf '%s\n' "$SVIX_LOCAL_URL"

Replace that example port if Docker reports a different mapping. If the Localtonet client runs on another machine, use the Docker host’s reachable LAN address instead of 127.0.0.1.

Run the reproducible transport check

curl \
  --connect-timeout 5 \
  --max-time 15 \
  --silent \
  --show-error \
  --output /dev/null \
  --write-out 'HTTP %{http_code} remote=%{remote_ip} connect=%{time_connect}s total=%{time_total}s\n' \
  "$SVIX_LOCAL_URL/"

This request is deliberately a transport check. Any actual HTTP status proves that curl connected to an HTTP server and received a response. A 401, 403, or 404 can still demonstrate transport reachability, but it does not establish that an authenticated Svix API operation succeeded. A reported 000, connection refusal, DNS failure, or timeout indicates that no usable HTTP response was received.

The evidence used for this revision does not establish a stable Svix health-check path or a universal authenticated request that is valid across server versions and deployment credentials. We therefore do not invent a /health endpoint, publish a secret, or present a guessed request as application verification.

Complete authenticated Svix verification

Open the official Svix API reference that matches your deployed server capabilities. Select a read-only operation where practical, supply the authentication mechanism generated for your deployment, and execute it against SVIX_LOCAL_URL. Record the exact method, path, expected status, and redacted response in your own runbook.

This application test is successful only when Svix accepts the request and returns the response expected for that documented operation. An authorization failure confirms that the network path reached an application, but it is not authenticated success. Do not weaken Svix authentication to make the check pass.

Expose the verified Svix API with a Localtonet HTTP tunnel

Configure the tunnel only after the local URL responds from the device that will run our client. Use an HTTP tunnel because Svix exposes an HTTP API. Do not create TCP tunnels for PostgreSQL or Redis as part of this workflow.

HTTP Process Type options include Random Sub Domain, Custom Sub Domain, and Custom Domain. They serve the configured local content at a public HTTPS address. Current availability can vary by product configuration or subscription, so use the options displayed in the dashboard. Check current DNS requirements before configuring a custom domain.

The maintained workflow is also available in the Localtonet HTTP tunnel documentation.

Repeat the transport test through the public URL

Copy the public HTTPS base address assigned by Localtonet and place it in a separate variable. Do not append credentials to it.

SVIX_PUBLIC_URL="https://<assigned-public-host>"

curl \
  --connect-timeout 5 \
  --max-time 15 \
  --silent \
  --show-error \
  --output /dev/null \
  --write-out 'HTTP %{http_code} remote=%{remote_ip} connect=%{time_connect}s total=%{time_total}s\n' \
  "$SVIX_PUBLIC_URL/"

As with the local request, any real HTTP response establishes transport reachability but does not by itself prove authenticated API success. If the local test responds and the public test cannot connect, focus on the Localtonet client state, tunnel state, AuthToken selection, server selection, and configured local target.

Repeat the authenticated operation

Use the same Svix API method, path, body, and authentication that succeeded locally. Change only the base URL from SVIX_LOCAL_URL to SVIX_PUBLIC_URL. Matching successful results demonstrate that the remote client can reach and authenticate to the same Svix application through the public route.

Keep API credentials in a protected secret store or an appropriate environment variable. Do not place them in the public hostname, command history, screenshots, or client-side browser code.

Stop or delete the tunnel when appropriate

Stop the tunnel when remote access is temporarily unnecessary. Delete it if the public route should not be retained. Stopping or deleting the tunnel does not uninstall Svix or remove its PostgreSQL data. It changes only the Localtonet route.

Operate, back up, restart, and upgrade the deployment

Use the correct Compose lifecycle command

Run lifecycle commands from the same server directory and repository revision used to start the project.

docker compose ps
docker compose stop
docker compose start
docker compose restart
docker compose logs --tail=200

stop stops containers while retaining them. start starts those existing containers. restart restarts them. After any restart, check status, logs, port publication, and both verification layers again.

To remove the Compose containers and project network while retaining named volumes, use:

docker compose down

Do not casually add the -v or --volumes option. That option removes named volumes declared by the Compose project and can destroy PostgreSQL or Redis data stored there. Inspect the actual volume configuration and verify backups before destructive teardown.

Back up application state, not just configuration files

Saving the repository and Compose file is not a database backup. PostgreSQL contains Svix event data, so establish a database-aware backup process and test restoring it into an isolated environment. The exact backup command depends on the database name, credentials, host, storage design, and operational platform, none of which should be guessed in a general tutorial.

If Redis is selected, preserve it according to the queue durability requirements of your deployment. Svix recommends Redis persistence so tasks survive server restarts and upgrades. Confirm that its eviction policy does not remove keys without explicit expiration.

Record where Docker stores named volumes or bind-mounted data. Include configuration, secret references, image versions or digests, the Git revision, and restoration instructions in the deployment runbook. Test recovery before relying on the service for important delivery workloads.

Pin and review images

Inspect image references with docker compose config --images. Mutable tags are convenient for development but allow a future pull to retrieve a different image. Controlled environments should pin tested versioned tags or immutable digests according to their release process.

Image pinning does not eliminate maintenance. Monitor Svix, PostgreSQL, Redis when used, Docker, and operating-system updates. Promote updates through a test environment before applying them to a deployment that stores real events.

Use a deliberate upgrade sequence

Before changing the repository revision or image references, record the current Git commit and rendered image list, create verified backups, and review the target release’s migration and compatibility guidance. Then obtain the intended revision, review the Compose diff, pull the selected images, and recreate the project.

git rev-parse HEAD
docker compose config --images
docker compose ps

git fetch --tags --prune
git checkout <reviewed-target-commit-or-tag>

cd server
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200

The placeholder must be replaced with a revision you reviewed. Do not run an upgrade solely because a new mutable image is available. After the change, rediscover the published port and repeat the local transport test, authenticated local test, public transport test, and authenticated public test.

Protect credentials and restrict exposure

Creating a tunnel changes reachability, not authorization. Generate the Svix JWT secret securely and restrict it to the server and administrators who require it. Remote API clients should receive only the credentials and permissions needed for their role.

Do not expose PostgreSQL, Redis, the Docker API, or unrelated management interfaces through the Svix tunnel. Keep the public route scoped to the verified HTTP listener. Stop it during periods when remote access is not required.

Troubleshoot Svix Docker and Localtonet connectivity

Docker or Compose is unavailable

Run docker --version, docker compose version, and docker info. A missing command indicates an installation problem. A daemon connection or permission error means Docker exists but the current account cannot use it. Resolve that layer before investigating Svix.

Compose cannot find its configuration

Confirm the repository revision and current directory:

git rev-parse HEAD
pwd
ls
cd server
docker compose config --services

If the final command cannot find a configuration, inspect the checked-out repository structure and verify that the selected commit is complete.

A container exits or continuously restarts

Use docker compose ps and docker compose logs --tail=200. Identify the earliest meaningful error. Later failures may be consequences of an unavailable database, invalid secret, unsupported setting, failed migration, port conflict, or missing storage permission.

PostgreSQL cannot be reached

PostgreSQL is required. Confirm that its Compose service is running, that Svix uses the service address defined by the project, and that the configured credentials and database are valid. Inside a container, localhost refers to that container, not automatically to another container or the Docker host.

Redis cannot be reached

First determine whether the selected Svix configuration uses Redis. If it does, confirm that Redis 6.2.0 or later is reachable through the configured DSN. If your design intentionally does not use Redis, make sure the queue and cache settings are compatible with that design rather than merely deleting the Redis container.

No host port appears in Compose status

A service can be reachable only inside the Compose network if no host port is published. Review docker compose config, docker compose ps, and the container inspection output. The Localtonet client needs an address and port reachable from the device where it runs.

The local curl command reports HTTP 000

HTTP 000 is curl’s indication that no HTTP status was received. Read the accompanying error. Connection refusal often means no listener is bound to the selected address and port. A timeout suggests routing or filtering. An address-resolution error indicates an invalid hostname or DNS problem.

The local request returns 401, 403, or 404

Those are real HTTP responses and can establish transport reachability. They do not prove authenticated Svix API success. Use the current Svix API reference, the correct method and path, and private credentials generated for your deployment.

Svix works on the Docker host but not from the Localtonet client device

If the client runs elsewhere, do not target the Docker host’s loopback address. Test the Docker host’s LAN address and published host port from the client device. Review the Docker bind address, host policy, and local routing before changing the public tunnel.

The tunnel was created but the public URL is unavailable

Confirm that the correct AuthToken was selected, the associated client is connected, and Start was pressed. Then compare the configured local IP address and port with the local URL that passed the transport test. Creating a tunnel configuration does not start it.

The public URL returns an authentication error

This usually means the network path reached an HTTP application but the request was not accepted. Repeat the same authenticated request that succeeded locally and change only the base URL. Do not disable authentication or expose the server JWT secret to make the public test pass.

Outbound webhook delivery fails even though the tunnel works

The tunnel in this guide handles incoming calls from remote clients to the Svix API. Outbound webhook delivery uses a different path from Svix to the destination. Check destination DNS, outbound connectivity, destination availability, payload acceptance, and Svix delivery information rather than assuming the API tunnel controls outbound delivery.

Data disappears after teardown

Review the exact command used and the project’s volume definitions. docker compose down --volumes removes named project volumes. Restoring service requires a valid backup if persistent data was deleted. This is why volume inspection and restoration testing must happen before teardown or upgrade work.

Frequently asked questions