Complete first-run setup

Use the first-run setup wizard to turn a freshly installed Erde server into a running system. The wizard collects the database connection, generates the security keys, creates the first administrator, and optionally activates your license — then writes the production configuration so the server boots normally on every later run.

Before you start

• When the wizard appears: Erde runs the wizard only on a first run — when there is no appsettings.Production.json next to the server binary. Once that file exists, the server boots normally and the setup action endpoints (the POST api/setup/* routes) return 404. The client still queries GET api/setup/status, which responds with setupRequired: false in normal mode — that is how it detects setup is complete.
• Prerequisites: Erde must be installed and a database server (PostgreSQL or SQL Server) must be reachable from the Erde host. Have your database connection details ready, and your license key if you want to activate during setup.

The wizard is reachable only from the server itself: it binds to loopback, and it answers any connection from another machine with 403 Forbidden (this is what protects the wizard under IIS hosting, where IIS owns the binding). Open it on the Erde host at http://localhost:5000/setup (substitute the port you chose at install time if you changed it from 5000).

Steps

The wizard presents its screens in the order below. The license screen comes first and is optional; the database, deployment, and admin screens are required; email (Simple Mail Transfer Protocol, SMTP) and the ArcGIS key are optional and can be skipped.

1. Activate your license. This is the wizard's first screen. Enter your license key to activate against the Erde license server, or skip it and activate later. Activation is not required to finish setup, but without an active license the application blocks normal use until a license is activated — after setup, sign in and use the activation form on the License Required overlay (see Activate and manage your license).

2. Provide the database connection. Choose the provider and enter the server details. The wizard tests the connection against the server's default catalog (postgres for PostgreSQL, master for SQL Server) before the Erde databases exist.

   Field	What to enter
   Provider	Select PostgreSQL or SQL Server (stored as postgresql / sqlserver)
   Server	The database host name or address — required, must not be blank
   Port	The database port
   Authentication	The authentication type — SQL or Windows (SQL Server only)
   Username	The database account user name
   Password	The database account password

   Erde creates and uses two databases: erde_app for domain data and erde_platform for identity, settings, and tenancy.

3. Provide the deployment settings. Set the public base URL where users reach Erde, and the deployment mode. This step refines the hosting shape you picked in the installer (IIS Website or Windows Service) into the specific runtime mode. Choose a mode: Windows Service, directly accessible (service-direct), Behind IIS (in-process) (iis-inproc), or Behind IIS (out-of-process) or another reverse proxy (behind-proxy). Choose the last option when Erde sits behind IIS out-of-process or any reverse proxy; that mode requires at least one trusted proxy IP address.

4. Create the administrator account.

   Field	What to enter
   Email	A valid email address (must contain @) — this becomes the admin sign-in
   Password	At least 10 characters, with an uppercase letter, a lowercase letter, a digit, and a special character
   Confirm Password	Re-enter the password; the wizard blocks Next until the two match

   The password rules are enforced by the server. If any rule fails, the wizard reports every problem at once so you can fix them in one pass.

5. (Optional) Configure email. Provide the SMTP host, port, from-address, and credentials if you want Erde to send mail. Set the encryption mode to one of None, STARTTLS, or SSL/TLS; STARTTLS is the default. You can send a test message before continuing. Email can also be configured later under Administration, so you may skip this step.

6. (Optional) Provide an ArcGIS API key. Erde uses ArcGIS for map visualizations. Enter an ArcGIS Developer API key to enable map features, or skip this screen — map features are unavailable without a key. You can also set the key later under Administration. Map features require each user's browser to have outbound HTTPS access to *.arcgis.com (the Erde server itself does not need internet access) — on air-gapped networks, maps are unavailable.

7. Apply the configuration. On the review screen, confirm your input and select Finish Setup. The wizard validates the input, generates the security keys, builds the connection strings, writes appsettings.Production.json, runs the database migrations, and seeds the initial data (roles, the admin account, system settings, and the default application-database record). Erde generates three random 256-bit keys for you — you do not enter them:

   Key	Purpose
   Jwt:Key	Signs authentication tokens
   Encryption:AesKeyBase64	Encrypts sensitive data stored in the database
   Tokens:TokenHashSecret	Protects refresh tokens

8. Restart into normal mode. After the configuration is written, restart the server (the wizard schedules a restart). On the next start the production configuration is present, so Erde boots the full application instead of the wizard.

Result

Setup writes appsettings.Production.json next to the server binary, containing the database connection strings, the generated security keys (Jwt:Key, Encryption:AesKeyBase64, Tokens:TokenHashSecret), and your application and seeding settings. The admin password is written only long enough to seed the account, then removed from the file. The erde_app and erde_platform databases are migrated and seeded.

On the next run the server detects the production configuration and boots normally. Sign in with the administrator email and password you set, then continue with Create your first project.

Back up the production configuration with your database

appsettings.Production.json holds the AES (Advanced Encryption Standard) encryption key (Encryption:AesKeyBase64). If you lose this file, encrypted data in the database becomes unreadable. Back it up alongside the database — see Deployment.

Troubleshooting

Symptom	Cause	Resolution
The full application opens instead of the wizard	appsettings.Production.json already exists — setup is complete	This is expected after a successful setup. To reconfigure, restore from a known-good config or reinstall; do not delete the production file casually (you lose the AES key).
The POST api/setup/* action routes return 404	Setup is already complete; the setup action endpoints are removed in normal mode	The server is running normally — go to the sign-in page instead of /setup. GET api/setup/status still responds with setupRequired: false.
Database connection test fails	Wrong provider, host, port, or credentials; server unreachable	Re-check the values against your database server. Provider must be exactly postgresql or sqlserver, and Server must not be blank.
Admin password rejected	Password under 10 characters or missing a required character class	Use at least 10 characters with an uppercase letter, a lowercase letter, a digit, and a special character.
Admin email rejected	Email is blank or not a valid address	Enter a valid mailbox address that contains @.
"Behind proxy" mode rejected	behind-proxy mode requires a trusted proxy IP	Add at least one proxy IP, or choose service-direct or iis-inproc if Erde is not behind a reverse proxy.
Setup did not complete and the wizard reappears	The configuration step failed; Erde deletes the partial config so setup can be retried	Fix the reported error (commonly the database connection) and run the wizard again.

Related

• Install Erde
• Getting started
• Administration
• Deployment