Skip to content

Installation and Running

Prerequisites

  • Go 1.26+
  • MongoDB 8.2 (what the Docker Compose file and CI use). Some other 8.x releases refuse to start on Linux kernels 6.19 and newer.
  • Docker and Docker Compose (optional, for containerized deployment)

Running with Makefile

The project includes a Makefile for common tasks:

  • make build: Build the Phield binary.
  • make run: Run Phield locally (requires a running MongoDB).
  • make test: Run all tests. The MongoDB storage tests need a MongoDB instance at mongodb://localhost:27017, or at PHIELD_TEST_MONGO_URI if set. They skip when no instance is reachable.
  • make docker-up: Start Phield and MongoDB using Docker Compose.
  • make docker-down: Stop the services.
  • make clean: Remove the built binary.

Running with Docker

Images are published to Docker Hub for linux/amd64 and linux/arm64.

docker pull philterd/phield
docker run -p 8443:8443 philterd/phield

Phield serves HTTPS on port 8443 in the container, using a certificate it generates on start, so clients need -k until you supply one of your own:

curl -k https://localhost:8443/health

The dashboard is at https://localhost:8443/dashboard.

Pin a version rather than latest so a deployment does not move underneath you:

docker pull philterd/phield:1.0.0

Each release also publishes per-architecture tags (1.0.0-amd64, 1.0.0-arm64). Use the plain tag unless you need a specific architecture.

Without PHIELD_MONGO_URI, the container keeps everything in memory and loses it on restart. Point it at MongoDB to persist:

docker run -p 8443:8443 \
  -e PHIELD_MONGO_URI=mongodb://your-mongodb-host:27017/phield \
  -e PHIELD_API_KEY=your-key \
  philterd/phield

To supply your own certificate, mount it and set PHIELD_CERT_FILE and PHIELD_KEY_FILE. An existing certificate is never replaced. See Configuration.

Running with Docker Compose

The easiest way to run Phield along with its MongoDB dependency is using Docker Compose:

docker compose build
docker compose up

Phield will now be running on port 8443 (HTTPS) and listening for ingest requests.

The API is unauthenticated unless PHIELD_API_KEY is set. Set it in docker-compose.yaml to require an API key on every request. See Authentication.

Running Locally

If you have a MongoDB instance running locally, you can run Phield directly:

go build -o phield main.go
./phield

The binary reports its version:

./phield --version

Simulating Data

Once Phield is running, you can test it by sending simulated data. A script is provided for this purpose:

./simulate_data.sh

If the instance requires an API key, set PHIELD_API_KEY in the script's environment and it is sent with each request.

To check a running instance end to end, smoke-test.sh ingests data, reads it back, and verifies the results, exiting non-zero if anything fails. Set PHIELD_URL and, if the instance requires one, PHIELD_API_KEY.

PHIELD_URL=https://localhost:8443 ./smoke-test.sh

This script will send a series of baseline data points followed by a sudden spike to demonstrate trend detection and alerting. See the API Usage page for more configuration options.