unfiAgent/README.md

UNFI UDM Pro SE Security Copilot

Docker-only security copilot for UniFi UDM Pro SE:

• realtime logs/events
• config posture checks
• AI recommendations and remediation queue

1) Install Docker (Ubuntu 24.04)

sudo apt update
sudo apt install -y ca-certificates curl git

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Optional (run Docker without sudo):

sudo usermod -aG docker $USER
newgrp docker

2) Get the project

git clone <YOUR_REPO_URL> unfiAgent
cd unfiAgent

3) Create env + encryption key

cp .env.example .env
mkdir -p secrets
openssl rand -base64 32 > secrets/unfi_encryption_key
chmod 600 secrets/unfi_encryption_key

4) Start the app

docker compose up --build -d
docker compose ps
docker compose logs -f api

5) Open the app

• UI: http://<SERVER_IP>:5173
• First-time setup is guided in the login page.

First login (what "Bootstrap owner" means)

1. Open http://<SERVER_IP>:5173.
2. If no users exist yet, you will see First-time setup.
3. Create your first account (owner role): username + password.
4. Scan the shown MFA QR code, or click Copy key and paste it into Bitwarden/Authy/Google Authenticator manual setup.
5. Enter the 6-digit MFA code and sign in.

After this, you always use normal Sign In (username + password + MFA code).

6) Configure AI provider in the app (interactive)

In the UI:

1. Open AI Setup.
2. Pick provider (Local Ollama / OpenWebUI, OpenAI API, or Codex OAuth).
3. Enter model + provider connection settings.
4. Save and confirm provider status turns ready.

You do not need to edit provider settings in .env after this.

Recommended for your setup (OpenWebUI + Ollama)

In AI Setup, use:

• Provider: Local Ollama / OpenWebUI
• Model: qwen3-coder-next
• Base URL: http://YOUR_OPENWEBUI_HOST:8080
• Models Path: /ollama/api/tags
• Chat Path: /ollama/api/chat
• API key: only if your OpenWebUI endpoint requires it

If Docker says permission denied

Error example: permission denied while trying to connect to the Docker daemon socket

Fix:

sudo usermod -aG docker $USER
newgrp docker
docker compose up --build -d

If still failing, log out and log in again.

If api container is restarting

Check logs:

docker compose logs -f api

Two common causes:

1. Wrong database host in .env (localhost instead of postgres).
2. Missing or unreadable encryption key file.

Verify:

grep DATABASE_URL .env
ls -l secrets/unfi_encryption_key

DATABASE_URL must contain @postgres:5432 in Docker mode.

Quick recovery:

cp .env.example .env
docker compose down
docker compose up --build -d
docker compose logs -f api

Confirm everything runs in Docker

docker compose ps

You should see these 5 services as Up:

• web
• api
• worker
• postgres
• redis