# Configure oCMS *Published: 2026-11-02* oCMS reads environment variables and a site-specific `.env` file. Start with the file created by `ocms init my-site`, keep its generated keys, and change only the settings your installation needs. This guide covers a prebuilt installation; the [deployment guide](/deployment) adds the service and HTTPS proxy. ## 1. Finish the first local run Follow the [platform quick start](/download#download-quickstart-title), then open [localhost:8080/admin/](http://localhost:8080/admin/). On a freshly seeded site, the bootstrap login is `admin@example.com` with password `changeme1234`. Change both immediately in the account settings while the installation is still private. Remove sample accounts you do not need. Stop the foreground process with Ctrl+C. Edit `my-site/.env` and set `OCMS_DO_SEED=false` for subsequent starts. Keep the existing `OCMS_SESSION_SECRET` and `OCMS_MFA_KEY`. Restart from the site directory: ``` cd my-site ../ocms serve ``` The Download quick start runs in a subshell: after stopping it, your terminal returns to the directory where you started the download commands. Adjust `cd my-site` to the directory you actually created. Continue with the [editor's guide](/editors-guide) to prepare content. ## 2. Know which configuration wins 1. **Process environment:** variables exported in your shell, container or service take precedence over values in the file. 2. **Selected file:** oCMS normally reads `./.env` from its working directory. Set `OCMS_ENV_FILE` to select a different file. A selected file that is missing, unreadable or invalid prevents startup. 3. **Defaults and saved settings:** unspecified settings use application defaults or saved site settings where supported. Paths in the file are relative to the process's working directory, not automatically to the file's directory. Use absolute paths when the service's working directory differs from your interactive terminal. For example, run from the site directory while selecting its file explicitly: ``` cd /srv/ocms/my-site OCMS_ENV_FILE=/srv/ocms/my-site/.env /opt/ocms/ocms serve ``` Changing `.env` takes effect after restarting the process. If a value appears to be ignored, check the service definition and exported shell variables before editing the file again. Do not print or share the complete process environment; it can contain credentials. ## 3. Adjust local settings without replacing keys This is a **partial example** to merge into the generated file, not a replacement `.env`. It binds a development site to IPv4 loopback: ``` # Keep the generated OCMS_SESSION_SECRET and OCMS_MFA_KEY above. OCMS_ENV=development OCMS_SERVER_HOST=127.0.0.1 OCMS_SERVER_PORT=8080 OCMS_SITE_URL=http://localhost:8080 OCMS_DO_SEED=false OCMS_DB_PATH=./data/ocms.db OCMS_UPLOADS_DIR=./uploads OCMS_CUSTOM_DIR=./custom OCMS_LOG_LEVEL=info ``` `OCMS_SITE_URL` is the public origin used for absolute site links. Use a scheme and host, with a port when needed; do not append a page path, query, credentials or fragment. When changing the listener to port 8081, change the local site URL to `http://localhost:8081` too. `OCMS_ENV=development` is for local work. It is not a way to resolve a production startup error. ## 4. Keep data and theme paths clear `OCMS_DB_PATH` The SQLite database file. The application user needs write access to both the file and its containing directory so SQLite can create WAL and shared-memory files. `OCMS_UPLOADS_DIR` Uploaded media and generated image variants. Include this directory in the site's backups. `OCMS_CUSTOM_DIR` Custom theme files. Custom Go modules must already be compiled into the binary; placing module source here does not load it. `OCMS_ACTIVE_THEME` An explicit value overrides the saved admin selection at startup. Remove the override from both the file and the process environment if you want Admin → Themes to control the theme across restarts. See the [theme gallery](/themes). Run separate sites with separate database paths, upload directories, configuration files and listening ports. Avoid pointing a test installation at the production files. ## 5. Prepare production deliberately Keep the generated secrets stable. The session secret must be at least 32 bytes; the MFA key must also be at least 32 bytes and different from it. For an older installation missing a key, generate the missing value with `openssl rand -base64 32` and save it privately. Do not regenerate an existing MFA key: enrolled authenticator secrets depend on it. For the same-host reverse proxy in the deployment guide, merge these settings into the existing file, replacing the domain: ``` OCMS_ENV=production OCMS_DO_SEED=false OCMS_SITE_URL=https://cms.example.com OCMS_SERVER_HOST=127.0.0.1 OCMS_SERVER_PORT=8080 OCMS_TRUSTED_PROXIES=127.0.0.1/32 OCMS_API_ALLOWED_CIDRS=127.0.0.1/32 OCMS_REQUIRE_MFA=true ``` This example permits protected API-key requests from loopback only. Add the actual automation-client CIDRs when needed; do not use a catch-all range to silence a startup check. The [API cookbook](/api-cookbook) covers key scopes and source restrictions. These lines alone are not a complete production setup. Before changing environments, replace bootstrap credentials, deactivate the Developer module and unused import/integration modules, and configure hCaptcha for active public forms. Active webhooks, Embed or Migrator may require additional allowlists and secrets. Follow the [production preparation checklist](/deployment#site-files) and keep the production safeguards enabled. Restrict access to the file, for example `chmod 600 .env` when it is owned by the service user. Back up the original keys with the database using the [backup walkthrough](/backup-and-restore). Use [account security](/account-security) for enrollment and recovery. ## 6. Verify a change 1. Keep a private copy of the working configuration before editing. 2. Restart the correct site from its normal working directory and read the first startup error. A missing file, invalid key or integration-policy failure needs correcting before another restart. 3. Check `/health`, a known page, an uploaded image and the active theme. 4. Check generated links use the intended public domain and HTTPS, then sign in and complete MFA where required. ``` curl --fail --silent --show-error http://127.0.0.1:8080/health ``` Use the [configuration reference (GitHub Wiki)](https://github.com/olegiv/ocms-go/wiki/Configuration) for less common settings. For a version change, follow the [upgrade walkthrough](/upgrading) rather than replacing the site's configuration with a fresh example. --- [Source](https://ocms.tech/configuration)