Skip to content

Get the first-run setup status

GET
/setup/status

Returns whether first-run setup is open, how the server was configured when it started, the values the setup form starts with, and two flags the web app uses for routing.

No sign-in is needed, in either public-mode state, and that stays true after setup: anyone who can reach the server can read the database host, port and name, the storage backend and every prefilled value, including the administrator’s username, email and name and the SMTP host, user name and sender, if the operator set them. No password is included.

needs_setup is true while the server’s administrator count is zero. The count takes approved accounts whose own global role lists system.admin, or that were granted it for the whole install, and leaves out anyone with a global revoke. It doesn’t follow role inheritance, so someone can hold system.admin through a parent role without being counted. On a normal start, when the count is zero, the server gives an admin account the Admin role before it serves any request, which normally closes setup, so on a running install this is usually false. It turns true again if the count drops to zero while the server runs.

deployment and defaults are the values the server read when it started, not the saved site or email settings, and change only after a restart. public_mode and self_registration_enabled are read for each request and reported as false when they can’t be read. The count and the two flags are separate reads, so the answer can mix moments and can be out of date by the time it arrives. Server errors get a plain-text 500.

The setup status, the start-up configuration and the form prefills.

object
needs_setup
required

True while the server’s administrator count is zero: approved accounts whose own global role lists system.admin, or that were granted it for the whole install, minus anyone with a global revoke. Inherited roles and team permissions aren’t counted, so this can be true while someone still holds system.admin. The server sets up an administrator at start-up when the count is zero, so this is usually false; it turns true again if the count drops to zero while the server runs.

boolean
deployment
required

The database the server connects to and the storage backend it uses, as set when it started. No database user name or password is included.

object
db_host
required

The database host name.

string
Example
postgres
db_port
required

The database port.

integer
Example
5432
db_name
required

The database name.

string
Example
artist_alley
storage_backend
required

fs or s3.

string
Example
fs
defaults
required

The values the setup form starts with, read from the server’s AA_SETUP_DEFAULT_* settings when it started. An empty string means there is nothing to prefill. The port must be a whole number or the server doesn’t start, and the encryption is normalised as smtp_encryption says; nothing checks that an address, URL or port is usable. No password is included.

object
admin_username
required

From AA_SETUP_DEFAULT_USERNAME; empty when not set.

string
admin_email
required

From AA_SETUP_DEFAULT_EMAIL; empty when not set.

string
admin_fullname
required

From AA_SETUP_DEFAULT_FULLNAME; empty when not set.

string
site_name
required

From AA_SETUP_DEFAULT_SITE_NAME; Artist Alley when not set.

string
Example
artist-alley
site_base_url
required

From AA_SETUP_DEFAULT_BASE_URL; empty when not set.

string
smtp_host
required

From AA_SETUP_DEFAULT_SMTP_HOST; empty when not set.

string
smtp_port
required

From AA_SETUP_DEFAULT_SMTP_PORT; 587 when not set.

integer
Example
587
smtp_encryption
required

From AA_SETUP_DEFAULT_SMTP_ENCRYPTION, in any case: tls, ssl and smtps give tls, none gives none, and anything else, or no value, gives starttls.

string
Allowed values: none starttls tls
Example
starttls
smtp_username
required

From AA_SETUP_DEFAULT_SMTP_USERNAME; empty when not set.

string
smtp_from_address
required

From AA_SETUP_DEFAULT_SMTP_FROM; empty when not set.

string
public_mode
required

Whether the install shows its public pages to visitors who aren’t signed in. It’s read for each request and reported as false when it can’t be read. The web app uses it to decide where to send a signed-out visitor; the server applies the setting itself, so this flag never grants access.

boolean
self_registration_enabled
required

Whether people can create their own accounts. It’s read for each request and reported as false when it can’t be read. Only this flag is shown here; the other sign-up settings stay in the admin settings. register checks sign-up itself and refuses with 403 when it’s off, so this flag never opens sign-up.

boolean

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed