Upgrade from v1.3.1

Move a pfSense Actions v1.3.1 deployment to 2.0.0, which replaces the shared API key with a personal access token for each client and adds the operations console.

What Changed

Area	v1.3.1	2.0.0
Client sign-in	One `API_KEY` shared by every client, or a random key at each start when it's unset	A personal access token per client, each with its own scopes
Routes	`GET /`, `POST /ping`, `GET /reload-filter`, `GET /update-dyndns`, `POST /wol`	`GET /api/v1/connectivity`, `POST /api/v1/ping`, and `POST /api/v1/wol`, with `GET /`, `POST /ping`, and `POST /wol` kept as aliases, and the new `GET /api/v1/system`, also at `GET /system`
Responses	The status code and its standard text	JSON, with an error code and message when a request fails
Failed pfSense commands	`GET /` and `POST /wol` still returned `200`	`502`
`count` on `POST /ping`	Any number of attempts	1 to 10 ping attempts
Published port	`9898` on every interface	`22603` on every interface
Image	`mrjackyliang/pfsense-actions` from Docker Hub	Built on your host by the repository's `compose.yml`
Settings	Environment variables, read at every start	The operations console, which stores them in the controller database
Administration	None	The operations console at `/admin`, set up with a one-time setup code
Alerts	None	The console's Notifications page, which sends alerts to ntfy, Telegram, email, and eight other services when pfSense stops answering, sign-in is locked, or an action fails

Before You Upgrade

List each client that uses the v1 API key, and the routes it calls.
/reload-filter and /update-dyndns have no replacement in 2.0.0, so plan to handle filter reloads and Dynamic DNS updates in pfSense itself.
Note your v1 PFSENSE_SSH_IP, PFSENSE_SSH_PORT, PFSENSE_USERNAME, and PFSENSE_PASSWORD or PFSENSE_PRIVATE_KEY values, because you'll enter them in the console.

warning

The v1 workflow published mrjackyliang/pfsense-actions:latest along with a tag for each release, such as v1.3.1. The 2.0.0 workflow also tags stable releases as latest in that repository, so it's recommended to pin the v1 tag until you upgrade.

Upgrade Steps

Stop the v1 container, for example with docker stop pfsense-actions.
Start 2.0.0 from the repository root with docker compose up --build --detach.
Read the setup code with docker compose logs app, then create the administrator account as described in Install with Docker.
Open Connection, enter your v1 PFSENSE_* values, and select Test and save.
Create one token per client in Access tokens, with only the scopes it needs.
Update each client as described below, then remove the v1 container and image.

info

To skip retyping the connection, add your v1 PFSENSE_* variables under environment in compose.yml before the first start. pfSense Actions imports them as the saved connection, without testing it, and logs a warning because they're deprecated. Select Test connection to check it, then remove the variables.

2.0.0 doesn't read API_KEY, so you can delete it from your environment files.

Update Each Client

Replace the v1 API key with the client's own token, sent in the same Authorization: Bearer header.
Point the client at port 22603 instead of 9898, or set PFSENSE_ACTIONS_PORT to 9898 in the root .env to keep the old port. The HTTPS address of a reverse proxy works too.
Keep count on POST /ping between 1 and 10, since larger values now return 400.
Treat 502 as a failed request, and expect 503 from the ping route when the target never answers.
Move each client to its /api/v1 path when it's convenient. The v1 paths keep working, and both return the same JSON.

Route	v1 path	Scope
`GET /api/v1/connectivity`	`GET /`	`pfsense:read`
`GET /api/v1/system`	None, new in 2.0.0 and also at `GET /system`	`pfsense:read`
`POST /api/v1/ping`	`POST /ping`	`reachability:read`
`POST /api/v1/wol`	`POST /wol`	`wol:execute`

Roll Back

v1.3.1 kept no state on disk, so rolling back means stopping 2.0.0 and starting the v1 container again. docker compose down stops 2.0.0 and keeps its data volume for a later attempt.