Run Signals locally with Docker Compose

Prerequisites

• git and docker with the Compose plugin (docker compose).
• curl and unzip to drive the API and inspect the snapshot.
• Free TCP ports 8081 (Signals API) and 5432 (PostgreSQL) on your host.

1. Clone the repository

Everything you need ships in the repo, including the example stack:

git clone https://github.com/Elevarq/Signals.git
cd Signals

2. Start the stack

Bring both services up in the background. Compose boots a postgres:16-alpine instance with pg_stat_statements preloaded, runs init.sql to create a read-only signals role, and then starts the Signals daemon in dev mode connecting to the postgres service:

docker compose -f examples/docker-compose.yml up -d

The Signals daemon waits for PostgreSQL to report healthy before it starts. The example stack configures it entirely through environment variables — connecting to host postgres as user signals against database postgres, polling every 1m, and listening on 0.0.0.0:8081 so the port mapping reaches it. The read-only role is created by init.sql:

CREATE ROLE signals WITH LOGIN PASSWORD 'monitor_pass';
GRANT pg_monitor TO signals;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

3. Trigger a collection

Signals collects on its poll interval, but you do not have to wait. Ask it to collect immediately with signalsctlinside the container — it reuses the stack's SIGNALS_API_TOKEN, so there is no token to handle:

docker compose -f examples/docker-compose.yml exec signals \
  signalsctl collect now

4. Check status

Confirm the collector ran and the target is healthy. The /status endpoint returns the daemon and per-target state:

docker compose -f examples/docker-compose.yml exec signals \
  signalsctl status

5. Export a snapshot

Pull a portable snapshot archive to your host, then list its contents:

docker compose -f examples/docker-compose.yml exec signals \
  signalsctl export --output /data/snapshot.zip
docker compose -f examples/docker-compose.yml cp \
  signals:/data/snapshot.zip ./snapshot.zip
unzip -l snapshot.zip

The archive is a signals-snapshot.v1 bundle — metadata, the snapshot records, the query catalog, and the per-query runs and results. This is exactly the artifact you would hand to Elevarq Analyzer for review.

6. Tear down

When you are done, stop everything and remove the volumes so no state lingers:

docker compose -f examples/docker-compose.yml down -v

Where next

To run Signals against a real database, follow a cloud quickstart: Amazon RDS, Azure, or Google Cloud SQL. For a from-scratch setup on your own host, see Install Signals.