Deploy MoleSignal

MoleSignal ships as one binary and one container image. Configuration selects which roles a process runs: a single process can run everything, or the roles can be split across processes. Every deployment needs two external services: PostgreSQL and object storage.

Requirements

Component	Requirement
PostgreSQL	Stores metadata, identities, the file catalog, and product resources. PostgreSQL is the only supported metadata database. The Compose sandbox and the Kubernetes manifests use PostgreSQL 17.
Object storage	Stores Parquet files, search indexes, and profile blobs. Use `s3` (AWS S3 or an S3-compatible service such as RustFS, Cloudflare R2, or Alibaba Cloud OSS), `azure`, or `gcs`. The `local` backend is for a single node and for development.
Compute	Linux on x86-64 or arm64 with the container image (`linux/amd64` and `linux/arm64`). The sandbox needs about 2 GB of memory.
Intake disk	A persistent local volume for the write-ahead log (WAL) on every node that runs the `intake` role.

Memory and disk use depend on the ingest volume, the number of active streams, and the cache settings in Configuration. Size from observed usage: the Home page shows raw and compressed intake volume, and the process exposes Prometheus metrics at /metrics. See the Production checklist.

Container image

The image is published as ghcr.io/molesignal/molesignal. Each release publishes a version tag (for example 26.1.0.0) and a channel tag (for example alpha). Pin the version tag in production.

docker pull ghcr.io/molesignal/molesignal:26.1.0.0

The same image serves every role. The runtime variable RELEASE_CHANNEL (alpha, beta, rc, or stable) labels the deployment maturity and does not change the binary. The web UI is embedded in the binary and served on the HTTP port.

Deployment options

Docker Compose
Binary and systemd
Kubernetes

The repository ships deploy/docker/docker-compose.yaml with two profiles. Both start PostgreSQL 17 and RustFS, and run the MoleSignal image from ghcr.io/molesignal/molesignal.

# Everything in one process: serves the complete product
docker compose -f deploy/docker/docker-compose.yaml --profile standalone up

# One container per role
docker compose -f deploy/docker/docker-compose.yaml --profile multirole up

The multirole profile deploys one container per role. The router publishes the web UI and the HTTP API on 5080 and the OTLP gRPC receiver on 4317. See Role-based deployment.The standalone service publishes 5080 and 5082. It does not publish the OTLP gRPC port 4317. To send OTLP gRPC from the host, add a 4317:4317 mapping to the service.The Compose file is a sandbox: it uses default credentials, a development cipher key, and a development MS_SELF_TELEMETRY_CLUSTER_TOKEN for the multirole profile. Replace them before storing real data. See the Production checklist. The sandbox bucket is private.

Install the release binary, the configuration file, and the GeoIP database, then run MoleSignal as a systemd service.

sudo useradd --system --home-dir /var/lib/molesignal \
  --shell /usr/sbin/nologin molesignal
sudo install -Dm755 bin/molesignal /usr/local/bin/molesignal
sudo install -d -o root -g molesignal -m 0750 /etc/molesignal
sudo install -o root -g molesignal -m 0640 \
  conf/config.toml /etc/molesignal/config.toml
sudo install -Dm644 deploy/systemd/molesignal.service \
  /etc/systemd/system/molesignal.service
sudo install -Dm644 mmdb/dbip-city-lite.mmdb \
  /usr/share/molesignal/mmdb/dbip-city-lite.mmdb

Set the runtime channel in /etc/molesignal/molesignal.env:

RELEASE_CHANNEL=alpha

Edit /etc/molesignal/config.toml for PostgreSQL, object storage, and secrets, then start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now molesignal
sudo systemctl status molesignal

The unit uses /var/lib/molesignal as its state directory and grants CAP_NET_BIND_SERVICE so that the built-in TLS listener can bind ports 80 and 443.

The manifests in deploy/k8s/ use one image for every role. They reference the placeholder image molesignal:dev. Replace it with ghcr.io/molesignal/molesignal:<version> in every workload.The manifests do not include PostgreSQL or object storage. Provide PostgreSQL 17 under the service name postgresql (or edit meta_database.dsn in the ConfigMap) and any S3-compatible object store (edit object_store in the ConfigMap).The manifests deploy the role-split topology: the router workload serves the web UI and the HTTP API, and the other workloads run the data and background roles. To run one process that carries every role instead, start from 40-intake.yaml (a StatefulSet with a persistent volume for the WAL), set MS_NODE_ROLES to ["standalone"], add the Service port 5080, and probe /api/v1/healthz.

Workload	Kind	Replicas	Role
`router`	Deployment	2	`router`: the web UI, the HTTP API, and OTLP gRPC
`intake`	StatefulSet	2	`intake`, with a 20 Gi persistent volume per replica for the WAL
`querier`	Deployment	2	`querier`
`compactor`	Deployment	1	`compactor`, replicas can be added
`alert`	Deployment	1	`alert`, replicas can be added

Split-role nodes authenticate the trace candidates and self-telemetry that they forward to each other with a shared MS_SELF_TELEMETRY_CLUSTER_TOKEN. Trace capture is on by default, so every workload reads the same value from the self_telemetry_cluster_token key of molesignal-secret. Create the namespace, the configuration, and the secret, then apply the workloads:

kubectl apply -f 00-namespace.yaml
kubectl apply -f 10-configmap.yaml
kubectl create secret generic molesignal-secret -n molesignal \
  --from-literal=object_store_access_key="<access-key>" \
  --from-literal=object_store_secret_key="<secret-key>" \
  --from-literal=cipher_key="$(openssl rand -base64 32)" \
  --from-literal=self_telemetry_cluster_token="$(openssl rand -base64 32)" \
  --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -f 30-router.yaml -f 40-intake.yaml -f 50-querier.yaml \
              -f 60-compactor.yaml -f 70-alert.yaml

The workloads select their role with the MS_NODE_ROLES environment variable. Check the cluster through the router:

kubectl -n molesignal port-forward svc/router 5080:5080
curl http://127.0.0.1:5080/api/v1/healthz

The web UI is embedded in the binary. Expose port 5080 of the router workload through an Ingress or load balancer.The router workload serves the full API on 5080, and its readiness probe requests GET /api/v1/healthz. Every other workload serves a health, readiness, and metrics listener on 5080 and uses GET /api/v1/readyz as its readiness probe. For intake, the listener starts after WAL replay, so a ready pod accepts writes.

See Role-based deployment for roles, scaling, and high availability.

Ports

Port	Purpose	Exposure
`5080`	Web UI, HTTP API, `/metrics`, and the health endpoint. On every role except `router` and `standalone`, only health, readiness, and metrics.	Public behind TLS on `router` and `standalone`. Private on the other roles.
`4317`	OTLP gRPC receiver. Plain gRPC without TLS.	Public only behind a TLS-terminating proxy or inside a trusted network.
`5082`	Internal gRPC for node-to-node traffic: write forwarding, query forwarding, and scan shards	Private. Never expose.
`5083`	Arrow Flight SQL for database clients. Disabled by default.	Optional, behind TLS.
`5084`, `5085`	Probe Agent registration and control for synthetic monitoring private locations	Only when Probe Agents run outside the node.
`80`, `443`	Built-in TLS listener with automatic certificates, when `[http.tls].enabled` is `true`	Public.

Health and metrics

GET /api/v1/healthz is public. It returns 200 with {"status":"ok"}, or 503 with a reason while the intake WAL replays or when the object store is unreachable. Use it for container and load balancer probes.
GET /metrics is public and returns Prometheus metrics. Restrict it at the proxy or network layer.
GET /api/v1/readyz and GET /api/v1/version require a bearer token on a standalone or router node. version returns the version, commit, build id, release channel, and edition.
A node in a role-split cluster that does not serve the full API answers GET /api/v1/healthz, GET /api/v1/readyz, and GET /metrics without authentication on the same port.

See Self-observability for the metrics and the built-in telemetry of the service itself.

Get started

Data

Observe

Query and correlate

Reliability

AI ops

Collaboration

Admin

Deploy & operate

Best practices

Resources

Requirements

Container image

Deployment options

Ports

Health and metrics

​Requirements

​Container image

​Deployment options

​Ports

​Health and metrics

Requirements

Container image

Deployment options

Ports

Health and metrics