Self-host ArgueSecure

Run it on your own server with Docker Compose from prebuilt images: two files and no build. The commands on this page are pinned to the latest release.

What you need

Docker and Docker Compose, and nothing else: PHP, Node, MariaDB and Redis all run in containers. The stack starts six of them: the app (nginx and php-fpm), Reverb for the live websockets, a queue worker, a scheduler, MariaDB and Redis. Only the app publishes a port. It runs on a home server as readily as in a data centre. The optional assistant needs more memory, as described below.

Quick start

In an empty directory:

curl -fsSLO https://raw.githubusercontent.com/danionita/arguesecure-onlinev2/v2.7.0/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/danionita/arguesecure-onlinev2/v2.7.0/.env.example -o .env
sed -i "s|^DB_PASSWORD=.*|DB_PASSWORD=$(openssl rand -hex 16)|; s|^DB_ROOT_PASSWORD=.*|DB_ROOT_PASSWORD=$(openssl rand -hex 16)|; s|^ARGUESECURE_VERSION=.*|ARGUESECURE_VERSION=2.7.0|" .env
docker compose up -d

The sed line sets the two database passwords, which .env.example leaves empty (the database will not start without them), and pins the release, 2.7.0. The images are public on the GitHub Container Registry, so pulling them needs no login. They are ghcr.io/danionita/arguesecure:2.7.0 and ghcr.io/danionita/arguesecure-assistant:2.7.0.

On its first start the stack generates an APP_KEY and three REVERB_* secrets and logs them prominently. Keep them: losing them invalidates every encrypted cookie, and the two-factor secrets are encrypted with APP_KEY. It also runs the database migrations. Then open http://localhost:8000, or the port you set as APP_PORT.

DATA_PATH in .env sets where persistent data is stored (the database, Redis and the app's storage); it defaults to ./data.

The first administrator

There is no default account, and none is ever created for you. While no account exists, the app shows a setup screen where you create the first administrator, which also loads the bundled templates. After that, administrators create accounts under Admin, Users, one at a time or in bulk from a CSV file. There is no public registration.

Two-factor authentication and OpenID Connect single sign-on are set up from the profile page and the admin area. See Features for what they do.

Behind a reverse proxy

To serve ArgueSecure through SWAG, nginx, Traefik or similar, set APP_URL in .env to the public HTTPS address and recreate the containers. The proxy-trust settings this relies on are in the deployment spec, section 4.

Raise the proxy's header buffers. Responses can carry large headers, and without this, full page loads fail with 502 "upstream sent too big header". In nginx or SWAG:

proxy_buffer_size 32k;
proxy_busy_buffers_size 64k;

The live connection uses websockets, so the proxy must pass the upgrade headers on. Nothing in the repository hardcodes a host, domain or path.

Upgrades

Set ARGUESECURE_VERSION to the new release (2.7.0 pins one release, and 2.7 follows a minor line), then pull and restart. Migrations run when the app container starts. Take a database dump first, and read the release notes for what changed.

# in .env, set ARGUESECURE_VERSION to the new release, then:
docker compose pull
docker compose up -d

Add --profile assistant to both commands if you run the assistant. Upgrading to 2.7 signs everyone out once, because sessions moved from Redis to the database.

Templates already loaded stay as they were. When a release adds templates, load them into your instance with the seeder. It creates no users and skips templates that exist:

docker compose exec app php artisan db:seed --class='Database\Seeders\SampleContentSeeder' --force

Backups

Take a database dump before every upgrade:

docker compose exec db mariadb-dump -u"${DB_USERNAME}" -p"${DB_PASSWORD}" "${DB_DATABASE}" > backup.sql

The versions on an assessment's History page protect against mistakes inside the app. They are not a backup against losing the server. A single assessment can also be exported as JSON from its Export menu, a portable copy of all its data. A scheduled export of every assessment is not built, so until then the database dump is the backup. Keep .env too: it holds the keys that decrypt stored secrets.

The optional assistant

The assistant runs on the same server and sends nothing elsewhere. The small preset needs about 6 GiB of memory and a 4.2 GB download, and the large one about 28 GiB and 14.2 GB. Install a preset, start the container, then switch it on under Admin, AI assistant.

docker compose run --rm --build assistant-install small   # or: large
# set ASSISTANT_ENABLED=true in .env, then:
docker compose --profile assistant up --build -d

What it does and what it never does is on the features page. The switches, the thread count and switching presets are in the README and the assistant guide.

What leaves your server

ArgueSecure sends no telemetry. It checks new passwords against the Pwned Passwords range service, which receives only part of a hash, it contacts your identity provider if you configure single sign-on. Assessments stay on the server, and the app loads no font, script or image from another origin.

Get help or look further

The documentation lists the specs behind each part of the stack. If something here does not work, open an issue on GitHub with the release number and what you ran.