Skip to content
Scryer Docs

First-Run Setup

A new Scryer instance asks one question before anything else: should people need a password to use it? You can’t use Scryer until you answer. The choice is required on every new database from Scryer 0.21.22 onward. There’s no default, so an instance can’t end up open just because nobody got around to securing it.

Two other things happen on this screen when you need them. You can restore a backup instead of starting fresh, and you can protect the whole screen with a one-time setup code.

Choose How People Sign In

Section titled “Choose How People Sign In”

Open Scryer in a browser and you’ll see Set up access to Scryer, with two options.

Require an administrator password is the right choice for most installs. Enter a password for the built-in admin account, and Scryer signs you in and continues to the setup wizard. The screen shows the minimum length, which is 8 characters unless you’ve changed it.

Continue without authentication skips sign-in entirely, and every browser that reaches Scryer acts as administrator. You have to tick a box confirming you understand that before you can continue. Your network restrictions still apply, so this suits an instance that only you can reach, such as one on a home network or behind a VPN. See Running Without Authentication for how Scryer treats public clients in this mode.

You aren’t locked into either answer. Scryer remembers your choice across restarts and won’t ask again, and you can turn sign-in on later by following Form Login And Account Switching.

When Only One Option Is Available

Section titled “When Only One Option Is Available”

If SCRYER_AUTH_ENABLED is set, it decides the answer and Scryer disables the other option. true leaves only the password option, and false leaves only Continue without authentication. The Compose file Scryer generates sets it to false, so remove that line if you want to choose a password on this screen.

Skip The Screen With A Bootstrap Password

Section titled “Skip The Screen With A Bootstrap Password”

If you set SCRYER_ADMIN_PASSWORD or SCRYER_ADMIN_PASSWORD_FILE before the first start, Scryer never shows this screen. It creates the administrator from your temporary password, and the first sign-in asks you to replace it. There’s no setup code in this case either, because nobody is left to make the choice.

This is the best fit for automated deployments, and for any instance that’s exposed from the moment it starts. The examples are in First-Time Boot Password Configurations.

Setup Code

Section titled “Setup Code”

Until someone answers the question on this screen, anyone who can reach Scryer can answer it. They could set the administrator password themselves, or restore a backup of their own, and you’d find out when you tried to sign in.

That’s rarely a problem on your own machine or home network, where you’ll finish setup a minute after Scryer starts. It matters when strangers can reach the instance before you get there. The setup code closes that gap. With it turned on, Scryer prints a short code to its console when it starts, and the setup screen won’t accept a choice or a restore without it. Only someone who can read the server’s output can finish setup.

Do I Need One?

Section titled “Do I Need One?”

The setup code is off by default. Turn it on if other people or machines can reach Scryer before you’ve finished this screen.

Your situationSetup code
Scryer runs on your own computer, or on a home network you trustNot needed
You finish setup right after the first start, and nothing outside your network can reach itNot needed
You supply SCRYER_ADMIN_PASSWORD or SCRYER_ADMIN_PASSWORD_FILENot needed, because the screen doesn’t appear
Scryer runs on a VPS, a seedbox, or any host with a public addressRecommended
A reverse proxy or port forward already points at Scryer when it first startsRecommended
You share the network with people you don’t want administering Scryer, such as a dorm or an officeRecommended
A new instance might sit waiting for a while before anyone finishes setupRecommended

If you can get a bootstrap password into the deployment, that’s usually the better answer for an exposed instance, since the instance is never unclaimed at all. The setup code suits the cases where you’d rather pick the password in the browser, or want the choice of running without one.

Turn It On

Section titled “Turn It On”

Set SCRYER_REQUIRE_SETUP_CODE=true before the first start:

services:
  scryer:
    environment:
      SCRYER_REQUIRE_SETUP_CODE: "true"

On Homebrew, add the variable to $(brew --prefix)/etc/scryer/config.env. Other installs use the same variable through their environment configuration.

false, 0, and an empty value leave the code off. Any other value turns it on, so a typo can’t quietly remove the protection you asked for. Once setup is complete the variable has no effect, and you can leave it in place or remove it. It also does nothing on an existing instance.

Find The Code

Section titled “Find The Code”

The code looks like K7P-M4X, and it appears in a box headed SCRYER FIRST-RUN SETUP — ACTION REQUIRED. Scryer shows a Setup code field on the setup screen whenever one is required.

InstallWhere to look
Dockerdocker logs scryer 2>&1 | grep "setup code", or docker compose logs scryer with Compose
UnraidOn the Docker tab, click the Scryer icon and choose Logs
Homebrewgrep "setup code" "$(brew --prefix)/var/log/scryer.log"
Windows and macOS desktop appslogs/console.log in Scryer’s data folder
Portable binary in a terminalThe terminal you started Scryer from
Linux under systemdjournalctl -u scryer | grep "setup code"

You can type the code in upper or lower case, with or without the hyphen. It stays valid until setup finishes, and a wrong password or a mismatched confirmation doesn’t use it up.

Restarting Scryer replaces the code, so if you lose it, restart and read the new one. After five wrong attempts from the same address, Scryer stops accepting codes from it for a minute.

The code only goes to the console output that whoever runs Scryer controls. You won’t find it on the Logs page. If Scryer has nowhere to write the code, it stops at startup with an error instead of leaving you without one. Fix the console or service output, or supply a bootstrap password.

Restore A Backup Instead

Section titled “Restore A Backup Instead”

To bring an existing instance over, choose Restore from a backup bundle on the setup screen. Scryer accepts encrypted .enc bundles and asks for the bundle’s password. If a setup code is required, enter it first. The restore button stays disabled until you have.

A restore replaces the new database with the one in the backup, including its accounts and its sign-in settings. Scryer takes its answer from the backup, so you won’t be asked to choose afterward. Sign in with the accounts from the backup.

Restores run in the background on the server, so closing the page doesn’t stop one. The restore screen shows progress when you return. If you need to retry a failed restore while Scryer is starting up, the screen asks for the setup code again when one is required. Remember that a restart replaces it.

Existing Instances

Section titled “Existing Instances”

None of this applies to an instance that was already running before 0.21.22. Upgrading doesn’t show the setup screen and doesn’t change how anyone signs in. If you’ve lost access to an existing instance, see Locked Out.

Section titled “Related”