Skip to main content

First-run setup form

When you visit https://<your-site>/admin/ for the first time after uploading dist/admin/, the admin detects there's no Firebase configuration baked in (because config.js ships as a null stub for the no-build path) and renders an in-admin setup wizard instead of the normal sign-in page.

This wizard does what a developer would otherwise do via .env: collect Firebase + Flexweg credentials, validate them, and persist them so the admin works.

Prerequisites​

Before you start the wizard, you should have:

  • Firebase config copied from the Firebase Console (Project settings → General → Your apps → SDK setup) — six values: apiKey, authDomain, projectId, storageBucket, messagingSenderId, appId. See Firebase project setup.
  • Bootstrap admin email + password — the user you created in Firebase Authentication. The email MUST match the one pinned in your Firestore rules.
  • Flexweg API key, site URL, API base URL — see Flexweg account setup.

If anything's missing, fix that before opening the wizard.

The wizard​

The wizard has three steps:

Step 1 — Welcome​

Introduces the CMS and emphasises that:

  • The CMS itself is free — Flexweg never bills you for using it
  • It needs a free Firebase project to store data
  • It takes ~5 minutes to set up

Two buttons:

  • Firebase setup tutorial — opens the Firebase guide in a new tab. Click this if you haven't created your Firebase project yet.
  • I have created my Firebase project — proceeds to step 2.

Step 2 — Terms of use​

A 7-section terms of use document explaining:

  1. Free service — the CMS is provided free of charge by Flexweg
  2. Provided as-is — no warranty, may have bugs
  3. Your content, your responsibility — you handle copyright, image rights, GDPR, third-party licensing
  4. Your Firebase account, your security — you secure your Firebase project (passwords, rules)
  5. Limitation of liability — Flexweg isn't liable for revenue loss / data loss
  6. Your data stays yours — content lives in your Firebase + your Flexweg, no third-party transmission
  7. Fair use — illegal / fraudulent use may result in hosting suspension

A checkbox at the bottom: I have read and accept the Terms of use. Until ticked, the Continue button is disabled.

Click Continue to configuration when ready.

Step 3 — Configuration​

Three sections of fields:

Firebase:

  • API key
  • Auth domain (e.g. your-project.firebaseapp.com)
  • Project ID
  • Storage bucket (e.g. your-project.appspot.com)
  • Messaging sender ID (numeric)
  • App ID

Paste each value from your Firebase config object.

Bootstrap administrator:

  • Email — the admin's login email (must match the user you created in Firebase Auth AND the email in your Firestore rules)
  • Password — the admin's password

Flexweg API:

  • API key — generated in your Flexweg dashboard
  • Site URL — e.g. https://mysite.flexweg.com (no trailing slash)
  • API base URL — pre-filled to https://www.flexweg.com/api/v1, change only if Flexweg gave you a different endpoint

Click Save & continue.

What happens when you click Save​

The wizard runs through six validation steps in order, showing a spinner overlay with the current step:

  1. Signing in to Firebase — initialises Firebase with the form values, then signInWithEmailAndPassword. Catches and reports auth errors clearly:

    • auth/invalid-credential → wrong email/password
    • auth/user-not-found → user doesn't exist in Firebase Auth
    • auth/api-key-not-valid → wrong Firebase config
    • auth/operation-not-allowed → Email/Password provider not enabled in Firebase Console
    • auth/too-many-requests → temporary lockout, wait or reset password

  2. Verifying admin email — checks auth.currentUser.email === form.adminEmail to catch typos. If they don't match, you get a clear error.

  3. Testing Flexweg API — pings /files/storage-limits with the API key. If the key is wrong (HTTP 401/403), the form rejects before any Firestore write.

  4. Saving configuration — writes config/flexweg to Firestore. If your Firestore rules don't grant write to this path, you get a specific error pointing to the rules section of the README with the admin email pinned in. Fix the rules and retry.

  5. Uploading config.js — writes a populated config.js to your Flexweg site (replacing the null stub). Subsequent admin loads will pick up the values from this file.

  6. Syncing theme assets — uploads each theme's CSS + companion JS files (menu-loader.js, posts-loader.js) to /theme-assets/ so published pages have something to reference. Non-fatal: if this fails, you can re-trigger via Themes → Sync theme assets later.

The overlay shows each step and the progress accumulates with green checkmarks. After step 6, the admin reloads automatically.

After the wizard​

Once the wizard reloads:

  • The admin loads config.js (now filled), reads its values via window.__FLEXWEG_CONFIG__
  • Initialises Firebase with the saved config
  • Picks up your existing sign-in session (so you don't have to log in again)
  • Lands you on the dashboard

The wizard never appears again on this deploy unless someone manually clears config.js on Flexweg.

What if something fails​

The wizard surfaces specific error messages for each failure mode, and the form preserves your entered values across retries — you only need to fix the broken bit.

Common issues:

"Email/password sign-in is not enabled"​

The Firebase project's Authentication has Email/Password disabled. Open Firebase Console → Authentication → Sign-in method → enable Email/Password.

"Firestore rejected the configuration write"​

Your Firestore rules don't allow writing config/flexweg. The error message includes the email it expects to see in the rules. Open Firebase Console → Firestore → Rules and ensure:

  • The bootstrap admin email matches what you typed in the form
  • The rules allow match /config/{docId} writes

See Firestore security rules for the recommended ruleset.

"Flexweg API key rejected"​

The Flexweg API key is invalid or expired. Open your Flexweg dashboard → Account → API → regenerate or verify the key. Paste the new value back in the form and retry.

"Could not sign in to Firebase. [auth/...]"​

Generic catch — the form appends the actual Firebase error code in brackets. Common codes:

  • auth/configuration-not-found — Firebase project's Authentication isn't fully configured. Re-check that Email/Password is enabled.
  • auth/internal-error — transient Firebase issue, retry in a moment.

Admin renders with no plugins / themes after success​

This happens when the dist was deployed without the per-plugin/per-theme bundles. The admin is configured but can't find externals to load. Check that /admin/plugins/<id>/bundle.js and /admin/themes/<id>/bundle.js exist on Flexweg. If they don't, your dist/admin/ upload was incomplete.

Path B equivalent (.env)​

If you're a developer using local builds with .env:

# .env
VITE_FIREBASE_API_KEY=AIza…
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=1234567890
VITE_FIREBASE_APP_ID=1:1234567890:web:abcdef
VITE_ADMIN_EMAIL=[email protected]

The Flexweg API key + site URL + base URL are NOT in .env — they're entered in Settings → General of the admin (Path B users still go through that screen). With .env filled, the in-admin wizard is bypassed entirely on first load.

Continue​