website template

template repository for project websites.

how to run

prerequisites:

• node.js 20.x
• pnpm 9.x

Tip

you can use pnpm to install the required node.js version with pnpm env use 20 --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".

the email service can be configured with these environment variables:

• EMAIL_CONTACT_ADDRESS (required): email will be sent to this address.
• EMAIL_SMTP_SERVER and EMAIL_SMTP_PORT (required): which smtp server to use.
• EMAIL_SMTP_USERNAME and EMAIL_SMTP_PASSWORD (optional): not needed on acdh-ch infrastructure, can be useful for testing with e.e. https://ethereal.email.

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 when developing locally http://localhost:3000/admin (this will save changes to the filesystem), or at https://template-website-astro.acdh-ch-dev.oeaw.ac.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.
• 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.

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.

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/.