clariah-at

project website for clariah-at.

deployed at https://clariah.at.

how to run

prerequisites:

• node.js 22.x
• pnpm 9.x

Tip

you can use pnpm to install the required node.js version with pnpm env use 22 --global

set required environment variables in .env.local:

cp .env.local.example .env.local

also, set environment variables required by validation and deployment github actions. use "variables" for every environment variable prefixed with PUBLIC_, and "secrets" for all others.

the default template accepts the following variables:

• PUBLIC_REDMINE_ID (required): service issue for this application in the acdh-ch redmine issue tracker.
• PUBLIC_APP_BASE_URL (required): the base url for this application. the default of "http://localhost:3000" should be fine for local development.
• PUBLIC_APP_BASE_PATH (optional): set this when deploying to a path other than "/".
• PUBLIC_BOTS (required): whether this website can be indexed by web crawlers like the google bot. supported values are "disabled" and "enabled", defaults to "disabled".
• PUBLIC_MATOMO_BASE_URL and PUBLIC_MATOMO_ID (optional): set these to support client-side analytics with matomo.
• PUBLIC_GOOGLE_SITE_VERIFICATION (optional): set this to verify site ownership for google search console.
• ENV_VALIDATION (optional): whether environment variables should be validated. supported values are "disabled", "enabled" and "public" (only validate public variables, which can be useful in a docker build context to avoid having to pass secrets to docker build), defaults to "enabled".

when adding new environment variables, don't forget to add them to .env.local.example as well.

install dependencies:

pnpm install

run a development server on http://localhost:3000:

pnpm run dev

Tip

this template supports developing in containers. when opening the project in your editor, you should be prompted to re-open it in a devcontainer.

how to edit content

use the admin ui at http://localhost:3000/admin when developing locally (this will save changes to the filesystem), or at https://clariah.at/admin (this will commit changes to the github repository).

how to deploy

• ask a sysadmin to create a new acdh-ch kubernetes project.
• create a new namespace in that project via rancher, and set the KUBE_NAMESPACE github variable to that namespace.
• adjust the app_name, which will be the name of the deployment in the above namespace.
• set the PUBLIC_URL github variable to the application's public url (e.g. "https://my-app.acdh-ch-dev.oeaw.ac.at"), and set the KUBE_INGRESS_BASE_DOMAIN to the public url's base domain (e.g. "acdh-ch-dev.oeaw.ac.at"). PUBLIC_URL should match PUBLIC_APP_BASE_URL.
• when deploying to a production domain (i.e. a domain not ending in "acdh-ch-dev.oeaw.ac.at"), set HELM_UPGRADE_EXTRA_ARGS to --set 'ingress.annotations.cert-manager\.io/cluster-issuer=acdh-prod' for "acdh.oeaw.ac.at" domains, or to --set 'ingress.annotations.cert-manager\.io/cluster-issuer=letsencrypt-prod' for any other non-oeaw domains, and ensure KUBE_INGRESS_BASE_DOMAIN is set correctly.
• if you haven't yet, create a service issue in the acdh-ch redmine issue tracker, and set the SERVICE_ID github variable to the issue number. this should match the PUBLIC_REDMINE_ID variable in your .env.local file.
• ensure required build args (prefixed with PUBLIC_) are referenced in both the Dockerfile, as well as the validation and deployment pipelines, and set as github variables.
• ensure required runtime environment variables are referenced in the validation and deployment pipelines, and set as github secrets. github secrets need to be prefixed with K8S_SECRET_ to be automatically copied to the runtime environment. in case you need secrets in the docker build context, you can mount a secret in the Dockerfile.
• ensure both the github repository, as well as the package registry is set to public.
• the PUBLIC_BOTS variable defaults to "disabled", which signals to web crawlers that the website should not be indexed. when deploying to a production domain (i.e. a domain not ending in "acdh-ch-dev.oeaw.ac.at") this should be set to "enabled".

if everything is set up correctly, every git push to the main branch will create a new deployment if the validation pipeline passes.

you can reference the template repository for a working setup.

Important

don't forget to include relevant data in the rss feed.

Note

by default, this will deploy a node server, which will serve pre-rendered pages, assets, and api routes. if you prefer a truly static build, which uses caddy as a fileserver, use the Dockerfile.static instead, and remove output: "hybrid" from astro.config.ts. you will also need to change the generate:search-index script to pagefind --site ./dist/.