The FedBOX control helper¶

Alongside the FedBOX server there is the fedboxctl helper binary which allows a server operator to execute some maintenance tasks:

The assumption is that the fedboxctl binary is used from the same folder where fedbox is being run from and that the .env files used for configuring them are present in the working directory.

If that’s not the case it supports passing the path using the --path argument, which in some cases might require the --env argument also.

Bootstrapping a storage backend¶

$ fedboxctl --path /tmp/fedbox storage bootstrap
{"level":"info","time":"2025-09-03T19:56:31+02:00","message":"Successfully created /tmp/fedbox db for storage fs"}
{"level":"info","time":"2025-09-03T19:56:31+02:00","message":"Successfully created FedBOX service https://fedbox.git/ for storage fs"}

Adding an OAuth2 client¶

$ fedboxctl oauth client add --redirectUri https://localhost:8080/callback
client's pw:
pw again:
Client ID: https://federated.local/actors/a4b1a21d-dc37-4e0c-99e0-1dd783a3da62
# The client exists as an Actor on the server as you can see.

Toggling the maintenance mode on and off¶

$ fedboxctl maintenance
# We can achieve the same using basic shell commands:
pkill -USR1 fedbox # problematic if there are multiple instances running
# using the per instance pid file
kill -USR1 $(cat /var/run/user/1000/com.example.fedbox.pid)

Reloading the configuration file¶

$ fedboxctl reload
# with pkill
pkill -HUP fedbox # problematic if there are multiple instances running
# using the per instance pid file
kill -HUP $(cat /var/run/user/1000/com.example.fedbox.pid)

Shutting down the server¶

$ fedboxctl stop
# with pkill
pkill -TERM fedbox # problematic if there are multiple instances running
# using the per instance pid file
kill -TERM $(cat /var/run/user/1000/com.example.fedbox.pid)