Ship your own defaults: site.config.json

site.config.json holds the starting content of the whole public site: the choir's name, the wording of every page, the colours, which features are on. The sample choir, Harmony Community Choir, is what it ships with. This page is for whoever installs the server and wants a new site to start with their own content rather than the sample, or wants to understand what Reset to defaults goes back to. Most sites never touch the file and do everything in Site Settings.

On a site we host

A site we host has no file to edit. Everything is changed in Site Settings: see How Site Settings works.

How the file and Site Settings fit together

There are two layers.

1. The file gives each setting its starting value. It is part of the software, in the site's folder, next to package.json.
2. What you save in Site Settings is kept in the site's database, one section at a time. When an admin saves a section, every field of that section is stored, including the ones they did not touch. That saved section is laid over the file.

So a section that nobody has saved follows the file. A section that has been saved keeps all its values, whatever the file says now. Reset to defaults on a section deletes what was saved for that section and the file shows through again. A small dot beside a section's name marks sections that have been saved.

This is why editing the file is quiet for a site in use: only sections nobody has saved change. It suits a new site whose admins have not been in yet.

When to edit it

• Before the first visit, to start with your own name, town, wording and colours, so that a new admin finds a site that already looks like theirs.
• When you set up several sites from one template, so each starts the same.
• To change what Reset to defaults goes back to.

For anything else use Site Settings, which is built for it, checks what you type, and survives updates. Saved settings are in the database, so they are included in your backups; the file is not.

The shape of the file

The top level has one entry per section of Site Settings. Each holds that section's fields:

Section in the file	Where it is changed in Site Settings
identity	Choir details, logo and browser icon
theme	Ready-made themes, colours, fonts, custom style sheet
features	Switch pages and features on or off
hero, about, concerts, promos	The home page: top, about, concerts, promo boxes
gallery, pastEvents	Gallery and Past Events wording
tickets	Your Tickets page
donate	Your Donate page
auditions, popup, pastDirectors, resources	Auditions, pop-up notice, past directors, resources
contact, footer, email	Contact, footer, email wording
memberPortal	Set up the member portal

An abridged look at the start of it:

{
  "identity": {
    "name": "Harmony Community Choir",
    "shortName": "Harmony",
    "tagline": "Singing together since 1998",
    "city": "Springfield",
    "foundedYear": 1998,
    "locale": "en-CA",
    "currency": "CAD",
    "timeZone": "America/Toronto"
  },
  "features": {
    "concerts": true,
    "ticketSales": true,
    "donate": true,
    "resources": false
  }
}

The names of the fields, their types and limits (how long a text may be, how many entries a list may have) are all in shared/site-schema.js, in the same folder. What each field means is explained on the pages in the table. The labels there are what you see in Site Settings.

Edit the values and leave the structure alone: do not remove fields or sections, and do not rename them. Start from the file you were given, so every field is present.

Make a change

On a self-hosted site

On a Node server:

1. Edit site.config.json in the site's folder, as a text editor opens plain text.
2. Restart the server. The file is read once, at start.
3. Reload the site. Only sections that nobody has saved in Site Settings change.

On Cloudflare Workers the file is built into the Worker when you deploy, so change it and run npx wrangler deploy again.

In Docker the file is inside the image, at /app/site.config.json. To use your own, mount it over that path in the Compose file. This has not been run here, and it works only while the site runs from the image rather than from a downloaded update (see below):

services:
  app:
    volumes:
      - ./site.config.json:/app/site.config.json:ro

The pages a visitor's browser loads also carry a copy of the file as it was when the release was made. It is used only while a page waits for the site's own answer, which then replaces it: a first-time visitor sees a blank page until the answer comes, or for up to five seconds if it is slow, after which the page is drawn from that copy. You cannot rebuild a downloaded release, so the copy stays the sample's.

The server checks the file when it starts

On Node, every section is checked against the schema at start. A problem is a warning in the log, not a stop, and the value is used as written:

[site.config.json] identity: Short name: is too long (60 characters at most)

The line names the section (as in the file), the field (as labelled in Site Settings) and what is wrong: too long, not a number, not a colour such as #1a2b3c, not a known icon, not a web address. Fix them and restart. A file that is not valid JSON, such as a missing comma, stops the server, and it will not start until it is fixed. Check it before you restart: node -e "JSON.parse(require('fs').readFileSync('site.config.json','utf8'))" prints nothing when the file is valid.

Your edits and updates

An update brings a new site.config.json with it, with new fields where the version added settings, and your edited file does not survive it:

• One-click updates download the new release into <DATA_DIR>/releases/<version>/ and run from there, so the site reads that release's own file. Your edited file in the installed folder is no longer read.
• Updating by hand unpacks the new release over the site's folder, replacing the file.
• A new image or a Cloudflare deploy brings the file from the release or from your checkout.

The sources do not set out a procedure for this; this is what follows from how updates work:

1. Keep your edited copy somewhere outside the site's folder, ideally under version control, alongside a note of which version it came from.
2. After each update, compare the new release's file with the one you started from, and apply your changes to the new file rather than copying your old file over it. A newer version may have added fields that your old copy lacks.
3. Restart (Node) or deploy (Cloudflare).

If that sounds like a chore, it is a sign to put the changes in Site Settings instead, where updates leave them alone. If you do edit the file and want to keep control of when it is replaced, set UPDATE_MODE=notify so that updates are installed by hand: see How updates work.

What a site's admins have saved is never touched by an update. Only the starting values change.