Skip to content

acdh-oeaw/template-app-nuxt

Repository files navigation

app template

template repository for nuxt 3 apps.

how to run

prerequisites:

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 NUXT_PUBLIC_, and "secrets" for all others.

install dependencies:

pnpm install

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

pnpm run dev

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").
  • 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.
  • 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 NUXT_PUBLIC_REDMINE_ID variable in your .env.local file.
  • ensure required build args (prefixed with NUXT_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.
  • the NUXT_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".
  • to enable runtime override of public runtimeConfig build values through runtime env vars note the naming conventions.

Important

this is a feature exclusive to nuxt 3. for most deployment scenarios it is not needed, but it can be useful for deploying multiple instances from a single build.

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.

template variants