# Settings

Understand the settings hub, select the homepage and distinguish saved site preferences from deployment configuration.

GroCMS 0.1.0 · Workspace · Administrators and designers · Reviewed 15 September 2026

## The Settings hub

Settings groups common administration destinations. Site settings opens the existing site-settings record when one is available. Brand & theme controls the public visual identity. Languages lets administrators add website languages; open Languages and translations in Documentation for the editing workflow. People & access manages accounts. API keys creates integration credentials. Export workspace downloads a content package. System updates manages GroCMS core releases on enrolled installations. Activity & accountability opens the audit log.

Each destination still enforces its own permissions. Administrators manage these destinations; core update actions also require a recent sign-in and an installation-owner grant. Designers can edit and publish design resources, including site settings and brand, but cannot manage people, API keys, exports or audit history. Editors manage ordinary content rather than design configuration. A card appearing on the hub is not evidence that your role can use its destination.

Sources: Settings hub (repository: `apps/cms/src/components/admin/settings.tsx`); Design and administrator permissions (repository: `apps/cms/src/cms/policy/index.ts`).

## Update GroCMS core

Open System updates in the administration sidebar to inspect the installed build and Latest release check. The version label alone does not confirm that this website has the latest changes. The How to update GroCMS section gives instructions for this installation; it opens automatically for externally managed sites.

> **Externally managed means no connection to the updater**
>
> This screen cannot check or install releases until an official Docker installation is enrolled with the managed updater. Ask your hosting operator or GroCMS distributor for the latest approved release and its notes. Your operator compares the actual deployed build, takes a verified database/media backup, preserves secrets and custom code, tests the candidate, deploys it through the existing hosting procedure, and verifies sign-in, public pages, media and the worker. Rerunning the installer is not an upgrade. Enabling managed updates for an existing website is a separate operator procedure: restore a verified backup into new managed storage and verify it before switching traffic.

On managed installations, an owner-authorized administrator must have signed in within the previous 15 minutes to check, test or install updates. Administrator access alone does not grant update authority. Opening this screen reads stored status; Check for updates makes a fresh request to the configured, signed GroCMS release catalogue. It does not install anything or check GitHub or npm. A failed check can retain older releases; an empty list or missing connection is not proof that GroCMS is up to date.

1. Choose Check for updates and inspect Latest release check and the last successful check time. Read the available release notes. Review update checks compatibility; inclusion in the catalogue alone does not guarantee that a release can be installed here. Resolve its assessment blockers.
2. Close the review and choose Test on a copy for the release, review its assessment, then choose Start rehearsal. It verifies isolated data and retains the installed release, but also pauses the website during copying and candidate verification. Plan a maintenance window; duration depends on site size. Wait for the result before continuing.
3. Review update again, then choose Install now or enter a future time and choose Schedule installation. Times use your browser's local time. The manager requires a verified recovery backup and rechecks compatibility before replacing the application. A changed installation can require another review. Review reinstall of this version follows the same checks and does not reset your database.
4. Open recovery and progress page after submitting and keep it available while the application restarts. Wait for verification, check Update history and verify the website. Cancel scheduled installation is available while scheduled or queued. If a result is uncertain, inspect progress before submitting again; ask your installation operator to resolve Recovery required.

Notification only is the default. The clearly labelled daily catalogue check can be disabled; manual checks remain available. Automatic installation is an opt-in policy limited to eligible maintenance and security releases within the selected time zone, days and window. Failed automatic releases pause for manual review.

> **Your content stays yours**
>
> Core updates retain your content and branding. Recovery before writing resumes can restore the matching backup and application. After the website reopens, recovery may replace newer edits and needs an explicit owner decision. If an older editor tab detects an update, saving pauses: use Keep draft and reload, then review the recovered draft. Download the draft first if browser recovery storage cannot be written.

Sources: Core update management screen (repository: `apps/cms/src/components/admin/system-updates.tsx`); Core update authority and request contracts (repository: `apps/cms/src/cms/api/updates.ts`); System updates guide (repository: `docs/system-updates.md`).

## Edit site settings

1. Open Settings and select Manage settings. If no record exists, the Site settings list lets an authorized user create one.
2. Open the existing canonical record rather than creating competing settings records. Only one settings resource per language can be published; attempting to publish another in that language produces a conflict. There is no active-record switch in the interface.
3. In its fields, enter Site name, choose a Page in Homepage if that is how your root page should be supplied, and set Site timezone as appropriate. The picker can include drafts, but the selected Page must be published before the settings can be published.
4. Save, review and publish the settings revision. Saving alone does not activate the change. Check the published root page and linked navigation afterwards.

| Field | Meaning in this build |
| --- | --- |
| Site name | A saved settings value. Public brand text is supplied by Brand & theme; this field is not a universal rename of all visible branding. |
| Homepage | A reference to a published Page used by public root-page resolution. Its own composition and template selection still determine the layout. |
| Posts archive path | A visible stored field, currently not used to change public routes. Archive paths come from the registered content-type routeBase. Changing this field alone does not move the post archive or rewrite navigation. |
| Site timezone | A stored site preference, defaulting to Africa/Johannesburg. Schedule entry currently uses the browser timezone; changing this field does not change every clock or reinterpret existing schedules. |

A home template may still supply the root layout when the selected page inherits its design. A page with a custom composition, even an empty composition, overrides that inherited template. Read Homepage before switching the homepage or replacing a layout so you know which resource is actually supplying the visible design.

Sources: Site settings fields and save flow (repository: `apps/cms/src/components/admin/resource-editor.tsx`); Public homepage and configuration selection (repository: `apps/cms/src/cms/services/public.ts`); Settings hub (repository: `apps/cms/src/components/admin/settings.tsx`); Settings publication validation (repository: `apps/cms/src/cms/services/content.ts`); Registered public archive routes (repository: `apps/cms/src/cms/definitions/index.ts`).

## Settings follow the same publication rules as content

Settings and brand are versioned resources. Their working and published revisions can differ, so an unfinished change can remain a draft while the current site continues to work. Revision history helps recover earlier values. Publishing validates references, including the selected homepage, against what can be used in the public site.

For a safe homepage change, prepare and publish the destination page first, then publish the settings change. Test the root URL, header links and footer links. If the result is wrong, inspect the page composition and template before assuming the settings did not save. A publication error about a dependency needs that referenced resource corrected or published; repeated clicks will not resolve it.

Sources: Settings publication validation (repository: `apps/cms/src/cms/services/content.ts`); Public homepage and configuration selection (repository: `apps/cms/src/cms/services/public.ts`).

## What belongs in server configuration

The Settings screen does not configure the database connection, public server origin, SMTP credentials, authentication secret, Docker ports, media storage directory or background worker. Operators set those through environment files and deployment tooling. Passwords and API secrets should never be pasted into a page, brand field or site name.

Changing from localhost to a real domain requires updating the deployment origin and configuring a reverse proxy and HTTPS, not just editing Site name. Likewise, email invitations and resets require SMTP setup outside this screen. The setup guides include the supplied commands and explain which process uses each configuration value.

Sources: Production services and environment (repository: `compose.yaml`); Environment configuration template (repository: `.env.example`).

## References

- Settings hub — repository path: `apps/cms/src/components/admin/settings.tsx`

- Core update management screen — repository path: `apps/cms/src/components/admin/system-updates.tsx`

- Core update authority and request contracts — repository path: `apps/cms/src/cms/api/updates.ts`

- System updates guide — repository path: `docs/system-updates.md`

- Site settings fields and save flow — repository path: `apps/cms/src/components/admin/resource-editor.tsx`

- Public homepage and configuration selection — repository path: `apps/cms/src/cms/services/public.ts`

- Settings publication validation — repository path: `apps/cms/src/cms/services/content.ts`

- Registered public archive routes — repository path: `apps/cms/src/cms/definitions/index.ts`

- Design and administrator permissions — repository path: `apps/cms/src/cms/policy/index.ts`

- Production services and environment — repository path: `compose.yaml`

- Environment configuration template — repository path: `.env.example`

## Related guides

- [Homepage](https://grocms.com/docs/homepage)

- [Brand & theme](https://grocms.com/docs/brand-and-theme)

- [People & permissions](https://grocms.com/docs/people)

- [API keys & content export](https://grocms.com/docs/api-and-export)

- [Production setup and upgrades](https://grocms.com/docs/production-setup)

- [Languages and translations](https://grocms.com/docs/languages-and-translations)