settings/hosting.json

{
  "cms_base_url": "https://cms.birkly.cloud",
  "public_site_mode": "project",
  "public_site_url": "https://birkly.cloud",
  "same_host_landing": "admin",
  "strict_admin_host": true
}

Field	Values	Notes
cms_base_url	HTTPS URL	Canonical admin + API base (required after onboarding)
public_site_mode	none | external | project	external = site hosted outside Birkly
public_site_url	HTTPS URL or empty	Required when mode ≠ none
same_host_landing	admin | public	When CMS and public share one host
strict_admin_host	boolean	Redirect /admin on public host to CMS URL (default true)

Editable in admin or on disk under /app/data/settings/hosting.json (Docker). Legacy installs with empty hosting.json may infer CMS URL from a cms.* request host on first access.

Routing

Request	CMS host	Public host
/	Admin (or same_host_landing)	Public site root
/admin	Admin	Redirect to CMS /admin
/api/*	API	API (CORS per Domains allowlist)

Public host with public_site_mode: project serves files from project/ at clean URLs (e.g. /about, not /project/about).

Dokploy domains checklist

• One app, all hostnames, Path /, Internal Path /, port 80
• Volume Mount → /app/data (not Bind Mount to host paths — Swarm often yields Containers (0) / 502)
• Test: CMS root → admin · public root → site · /api/deploy_revision.php returns JSON

Troubleshooting

Symptom	Check
Public site shows /project/ in URL	Internal Path must be /; confirm Hosting mode = project
/admin on public host stays on public host	Enable Redirect /admin on public host in Hosting settings
502 / Containers (0)	Bad mount type; switch to Volume Mount
Wrong host serves admin	Settings → Hosting — CMS URL and public site URL must match Dokploy domains
test.example.com redirects to production CMS	Test app uses prod volume or prod hosting.json — see Test and production below

Test and production (two separate installs)

Use this when you run two Birkly apps (e.g. cms.birkly.cloud for real work and test.birkly.cloud for experiments).

The one rule

Each app gets its own volume. Never mount the same volume name on both apps.

	Production app	Test app
Dokploy app name	e.g. Birkly CMS	e.g. Birkly Test
Domain	cms.birkly.cloud	test.birkly.cloud
Volume name	e.g. birkly-cms-data	e.g. birkly-cms-test-data
Mount path	/app/data	/app/data

If test uses prod’s volume (or a copy of prod’s data), opening test.birkly.cloud redirects to cms.birkly.cloud. That is expected — the saved CMS URL still says production.

Fix test redirecting to production

Pick one method. You only need one.

---

Method 1 — Environment variables in Dokploy (recommended)

Use this when you can open the Dokploy dashboard.

1. Log in to Dokploy (your server’s Dokploy URL).
2. Open your Project (the group that contains Birkly).
3. Click the test application — not the production one.

(If you only have one app, create a second app for test first.)

1. Open the Environment tab.

(Some Dokploy versions label this Env or put it under Advanced → Environment.)

1. Click Add variable (or the + button) three times and enter:

Name	Value
BIRKLY_CMS_BASE_URL	https://test.birkly.cloud
BIRKLY_TRUST_REQUEST_HOST	true
BIRKLY_PUBLIC_SITE_MODE	none

1. Click Save.
2. Click Deploy or Rebuild (not only Restart) so the container starts with the new variables.
3. Wait until Logs shows Containers (1).
4. Open https://test.birkly.cloud/admin in your browser — it should stay on test, not jump to cms.birkly.cloud.

Note: These variables require Birkly build from 2026-07-25 or later (PR #302). If they have no effect after rebuild, use Method 2.

---

Method 2 — Paste one command in Dokploy Terminal

Use this when Method 1 is unavailable or you prefer a permanent fix on the test volume.

1. In Dokploy, open the test application.
2. Open Terminal (or Exec / Console — a shell into the running container).

If there is no Terminal tab, use your host’s SSH and run docker exec -it <container> bash (ask whoever manages the server).

1. Paste this entire block and press Enter:

php /app/scripts/repair-hosting-domain.php https://test.birkly.cloud --public-mode=none

1. You should see Hosting repaired. and cms_base_url: https://test.birkly.cloud.
2. Open https://test.birkly.cloud/admin — no redirect to production.

If the script is missing (No such file), rebuild the test app from latest main on GitHub, then run the command again.

Manual alternative (same result, no script):

cat > /app/data/settings/hosting.json << 'EOF'
{
  "cms_base_url": "https://test.birkly.cloud",
  "public_site_mode": "none",
  "public_site_url": "",
  "same_host_landing": "admin",
  "strict_admin_host": true
}
EOF

Then reload https://test.birkly.cloud/admin.

---

Method 3 — Start test with a fresh volume (when nothing else works)

Use this if test and prod were ever mixed and you do not need to keep test data.

1. In Dokploy, open the test application.
2. Volumes → note the current volume name → remove the mount (or create a new volume name, e.g. birkly-cms-test-data-v2).
3. Mount the new empty volume at /app/data.
4. Deploy / Rebuild.
5. Open https://test.birkly.cloud/admin → create a new admin account (once).
6. Complete onboarding on test — hosting will use test.birkly.cloud automatically.

Production is untouched as long as you only change the test app’s volume.

---

How to know it worked

Open in your browser:

https://test.birkly.cloud/api/deploy_revision.php

Look at the hosting section (after latest deploy):

Field	Good value for test
cms_base_url	https://test.birkly.cloud
request_host	test.birkly.cloud
request_host_role	cms

If request_host_role is unknown and cms_base_url is still https://cms.birkly.cloud, the fix is not applied yet — retry Method 1 or 2.

Then you can test Marsk onboarding on test without affecting production.

Cannot log in on test after fixing hosting

The hosting repair script does not delete accounts. You usually see a login form because accounts still exist on the volume, but the password may differ from production (separate install = separate passwords).

Check what the test volume has (Dokploy → test app → Terminal):

ls -la /app/data/users/

If you see files like a1b2c3d4....json, admin accounts exist. Try the password you used when you first set up test, or use a full reset below.

Full reset on test only (new admin, empty site — keeps hosting.json):

php /app/scripts/reset-fresh-install.php --yes

Then open https://test.birkly.cloud/admin — you should get the onboarding wizard to create a new admin.

Complete wipe (Dokploy UI, no terminal): test app → Volumes → remove mount → add a new empty volume at /app/data → Deploy → open /admin → create admin once.

⚠️ Test and production share the same data (most common mistake)

If both Dokploy apps mount the same volume name (e.g. both use birkly-cms-data), they are not two separate websites — they are one Birkly install with two domain names.

Anything you do on test affects production immediately:

Action on test	Effect on production
Delete users / fresh reset	Production logins stop working
Create new admin (same email)	Production password changes to the new one
Install Marsk starter	Production content changes
Repair hosting URL	Can break which domain is “home”

Check in Dokploy: production app → Volumes → note the volume name. Test app → Volumes. If the name is identical, they share data. Test must use a different name (e.g. birkly-cms-test-data).

Recover production login: try https://cms.birkly.cloud/admin with the same email and password you created on test. Or reset:

php /app/scripts/reset-admin-password.php --email=YOUR@EMAIL.com --password='YourNewProdPassword123!'