Installation guide

First sign-in and operation

The first administrator, upgrades, backups, the coming-soon switch and the security policy.

The first administrator

Registration is open only to whoever holds an invite code, and the codes are generated in the console — which nobody can open yet. The first code is generated on the machine itself.

  1. Image: on the server, from the root of the repository, docker compose -f deploy/prod-allinone/docker-compose.yml exec -e MERYDION_DATA_ROOT=/var/lib/merydion/data merydion merydion-auth invite-code.
  2. Folder: in PowerShell, in the folder, $env:MERYDION_DATA_ROOT = (Resolve-Path .\data).Path; .\bin\merydion-auth.exe invite-code.
  3. The command prints a code in the form XXXX-XXXX-XXXX; invite-code 5 prints five.
  4. On the portal, click Sign in, then Create account: enter the code and register with the email written in ADMINISTRATORS, then confirm it with the code the verification email brings.
  5. Sign in: Diagnostics, at the foot of every page, opens the console, where the other invite codes are generated.

Tip If the verification email does not arrive, check the password of the mailbox: the sign-in service says at start-up when it is missing.

Upgrading

An upgrade replaces the image and keeps the data: they live in the container's volume, which belongs to the project and not to the image.

  1. On the development machine, with the updated repository, build the new image: .\rebuild_container_release.ps1 -NoSeedData.
  2. Copy it to the server, check it and load it as the first time: sha256sum -c merydion-allinone.tar.sha256 && docker load -i merydion-allinone.tar.
  3. Start with the same command as the first time: docker compose --env-file deploy/prod-allinone/.env -f deploy/prod-allinone/docker-compose.yml up -d notices the new image and recreates the container, with an interruption of a few seconds.
  4. Open the console on the Upgrade tab: where a row says Update available, click Run upgrade — until then the data functions of that service stay off.

Tip Before every upgrade, check in the diagnostics that the database copies are fine (the “Database copies” card) and copy the files: the database upgrade works on a copy and keeps the original until the copy is verified, but the copies are your own way back.

Copies and restore

Every service keeps a continuous copy of the databases it holds — accounts, document indexes, mail, chats — at most about a second behind, and restores it to any instant of the last seven days. The files themselves — documents, attachments, previews — are written once and never change: they are copied apart, or kept in an S3 bucket.

  1. Move the database copies off the machine: register a destination of the class backups on an S3 bucket or on another disk, and activate it.
  2. Image: copy the files, without the databases, while it runs: docker run --rm -v merydion-prod-allinone_merydion_state:/d:ro -v "$PWD/files":/b alpine sh -c 'tar czf /b/files-$(date +%F).tgz -C /d --exclude="*.db" --exclude="*.db-*" --exclude=./backups --exclude=./restores .' writes a dated archive into the files folder.
  3. Folder: stop it with .\stop.ps1, copy the data folder whole, then start it again.
  4. If an administrator has registered another destination for the files, copy its folder in the same round: the files born after it was activated are only there.
  5. Keep the copies away from the machine they protect.

Tip To bring one database or the whole installation back to an instant, stop the installation and run merydion-storage copies restore (the runbook's “Copies and restore” procedure): it writes the restored databases into a new folder, which then takes the place of the old one.

Putting the site in coming soon

Coming soon shows every visitor only a preview page while the installation is being prepared: the portal, the apps, Palatys and the console wait behind it, for administrators too.

  1. Sign in as an administrator and open https://merydion.example.com/coming-soon.html?enabled=true: the page confirms and the site is in coming soon.
  2. To bring the site back, open https://merydion.example.com/coming-soon.html?enabled=false: after the confirmation the page takes you to the home page.
  3. If you are not signed in, the page first asks you to sign in; an account that is not an administrator is told so, and nothing changes.
  4. The state is the file site/coming-soon in the data folder: removing it brings the site back even without the page.

Tip The coming-soon page exists in English and Italian; a visitor with another language gets the English one.

Turning on the visit statistics

The site can count its visits with Google Analytics 4, asking every visitor for consent first: until a visitor accepts, nothing from Google loads. The statistics stay off until the installation names its measurement ID, and the administration console never has them.

  1. In Google Analytics, create a property and a web data stream for the address of the site, and copy its measurement ID (it starts with G-).
  2. Image: in the .env file next to docker-compose.yml add MERYDION_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX and recreate the container with docker compose up -d. Folder: export the same variable in the session before start.ps1.
  3. Open the site in a private window: the notice on visit statistics appears at the bottom left, and “Cookie preferences” appears at the bottom of every page.
  4. To turn the statistics off, empty the variable and recreate the container: the notice disappears, and the browsers of those who had accepted stop loading Google Analytics.

Tip The privacy policy and the cookie policy already describe the statistics, in every language, for the installation that turns them on. In the property, set the data retention you want — Google keeps the data of a visit for at most 14 months — and leave Google signals off: the site turns them off on its side too.

Offering the site to search engines

Every installation tells search engines not to index it until it turns the indexing on: a copy of the site that is not the official one — a test installation, the installation of an organization — never competes with it in the results. The addresses that the pages, the previews and the sitemaps declare name the official site, https://merydion.eu, and the account pages, the console and the page of a missing address never enter an index.

  1. Only on the installation that serves the official site. Image: in the .env file next to docker-compose.yml add MERYDION_SITE_INDEXING=1 and recreate the container with docker compose up -d. Folder: export the same variable in the session before start.ps1.
  2. Check it: curl -I https://merydion.eu/ no longer shows the X-Robots-Tag: noindex header, and https://merydion.eu/robots.txt points at https://merydion.eu/sitemap.xml.
  3. In Google Search Console and in Bing Webmaster Tools, verify the domain with a DNS record and submit https://merydion.eu/sitemap.xml.
  4. To take the site off search engines again, empty the variable and recreate the container: every response says noindex again, and the engines drop the pages at their next visit.

Tip A portal generated for another address sets MERYDION_SITE_ORIGIN (for example https://www.example.com) when it is generated: the canonical addresses, the language alternates, the previews and the sitemaps then name that address. The page of a missing address answers in the language of its folder, with the status 404.

The portal's Content-Security-Policy

The portal's pages run under a strict Content-Security-Policy that the gateway sends: a page may use only its own files, requests to its own origin, images also from data: and blob:, and no frame of another site. It is what keeps a stray piece of markup from running code. The one exception is the visit statistics: the pages that may count visits also admit Google's gtag.js, on its path only, and the collection of Google Analytics, which load only after a visitor accepts.

  1. A customized portal with scripts or styles written inside its pages does not work: scripts and styles go in files of their own.
  2. window.MERYDION_AUTH_BASE, window.MERYDION_API_BASE and window.MERYDION_DIAGNOSTICS_BASE can move a family of requests only under another path of the same origin; an address on another origin is ignored, with an error in the browser console.
  3. The pages of the installation console carry the policy without the exception of the statistics and, in addition, cannot be shown inside a frame.
  4. The policy lives in apps/portal-csp.mjs and in the three Caddyfiles, and a test keeps them equal: change it in all four places together.

Tip The sign-in form of the identity service and the refusal page of the console arrive with a policy of their own, stricter still.

Back to the guide

Productivity, made in Italy.

Bring the whole suite to your team — simple, secure and entirely yours.