First Run

First run

The sequence from a clone to a working login, with the steps that are easy to skip and expensive to skip.

Before you start

• Docker 20.10 or newer, Docker Compose 2.0 or newer
• 8 GB RAM minimum, 16 GB recommended. This is eleven services plus PostgreSQL and Redis, not a single container
• Linux, macOS, or Windows with WSL2
• Disk space for the images and the databases

The sequence

git clone https://github.com/fabriziosalmi/wildbox.git
cd wildbox
cp .env.example .env

Generate real secrets before the first start. They are not optional and there are no safe defaults:

openssl rand -hex 32    # JWT_SECRET_KEY
openssl rand -hex 32    # DATABASE_PASSWORD

Set INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD in the same file. The first admin account is created from those values on first start, so a placeholder password becomes a real account with that password. Choose a strong one, and change it after the first login.

The repository ships a Makefile with secret generation and validation targets; use them if you prefer not to do this by hand.

docker compose up -d
docker compose logs -f gateway identity     # give it 2 to 3 minutes

Checking it came up

curl http://localhost/health          # gateway
curl http://localhost:8001/health     # identity

Then open the dashboard at http://localhost:3000 and the API documentation at http://localhost:8000/docs. Both are bound to localhost, so this must be the machine running Docker, or an SSH tunnel.

If a service is unhealthy, its own log is the first place to look:

docker compose logs <service-name>

The service names are in the service map.

When it does not come up

In rough order of likelihood:

1. Not enough memory. Below 8 GB, services are killed in ways that look like unrelated failures
2. A port is already taken. The gateway wants 80, 443 and 8080. netstat -tuln | grep -E '(80|443|8080|3000|8000|8001)'
3. Secrets missing or malformed in .env. Downstream services are meant to fail closed rather than start insecurely, so an absent secret is a refusal to boot, not a warning
4. Disk space. df -h

TROUBLESHOOTING.md is the detailed guide and is worth reading before opening an issue.

After the first login

1. Change the admin password
2. Read SECURITY.md before exposing anything
3. Configure credentials for the integrations you actually want, following the guides under docs/guides/
4. For production, follow SETUP_GUIDE.md rather than extending the development compose file

The compose file describes itself as a test rig

Worth reading the header of docker-compose.yml before deciding what this deployment is:

# Wildbox Security Suite - Integration Testing Orchestrator
# Coordinates all services with shared networking for end-to-end testing

It is the right file for a first run and for evaluating the platform. It is not the production path: SETUP_GUIDE.md is, and the difference is not cosmetic.

A word about exposing it

This platform holds credentials for your cloud accounts and telemetry from your endpoints. The default networking is deliberately closed: only the gateway listens beyond localhost, and the databases do not listen at all. Putting the dashboard or a backend port directly on a public interface undoes that in one line. If it needs to be reachable, put it behind the gateway with TLS and authentication in front.