Institution values, assets and theme from the deployment (#3244)¶
Part 1 of 5 of #500. Another institution runs the same images. It sets environment values and mounts one folder of files. It changes no code.
Decisions¶
- The operations links of the system logs page stay in the app. Each link is one value, and an empty value hides the link (decided on the issue).
- Each deployment shows only its own operations links. The page no longer lists the links of the three EPFL clusters on every deployment.
- The frontend reads every
APP_*value fromwindow.injectedEnvVariableonly. Theimport.meta.envfallback goes away.quasar dev,vite preview, the component tests and Storybook getinjectEnv.js,theme.cssand the assets from the samedocker/entrypoint.shas the container, throughfrontend/build/institution.mjs.APP_VERSIONandAPP_BUILD_TIMEstay build-time values, because they identify the bundle. - One script,
frontend/docker/entrypoint.sh, writes the values, the assets folder and the theme, and holds every check. It is POSIX sh with awk, because the nginx image has no Node and no Python.build/institution.mjsonly starts it and gives its output to Vite as the public folder. So the repository has one parser for the values file, one for the theme, and no second file server. - A wrong value stops the container, and the app has no page for it. A rollout with a wrong key then keeps the old pods. The browser does not check the values again.
- Every
APP_*value is public, becauseinjectEnv.jsgoes to every browser without a login. A key whose name hasSECRET,PASSWORD,TOKEN,CREDENTIALorPRIVATEstops the container. - The tab title is set at runtime from the text
app_document_title, because it names the institution. - The theme file sets CSS custom properties. The SCSS tokens read
var(--theme-*), so one image serves every institution. - The image has a neutral default for every asset except
theme.conf, as Keycloak ships its default theme (decided with the lead on 2026-11-13). A new deployment works with its values and one theme line. The accent color stays required, so the folder still givestheme.conf. A default is visible on the first page, unlike a wrong number. The startup log names the source of each file. An unknown file name stops the container, so a typo in an override is not silent. - The fonts default to Geist in the image.
theme.confcan point them at a font server. EPFL points them atenac-it-fonts.epfl.ch, so the licensed Suisse Int'l files are in no repository. - One folder is one institution:
values.env,theme.confand the assets. The repository names no institution. It holds only the neutral examplefrontend/institution-example/, which the dev server, the tests, Docker Compose and Storybook use by default. A real institution keeps its folder outside this repository. Before this rule, the EPFL data existed twice: 8 asset files and 17 values were the same in the app repository and the ops repository, and nothing kept them equal. A developer also had a fourth env file. A generic repository had a folder named after one institution. That folder was outside the./frontendDocker build context.
Values¶
Required values. If one is empty, entrypoint.sh stops the container
and the log names each empty value.
| Value | EPFL |
|---|---|
APP_INSTITUTION_NAME |
EPFL |
APP_INSTITUTION_NAME_FR_DE |
de l'EPFL |
APP_INSTITUTION_NAME_FR_A |
à l'EPFL |
APP_INSTITUTIONAL_ID_LABEL |
SCIPER |
APP_CONTACT_EMAIL |
the support address |
APP_USER_DOC_URL |
the user documentation |
APP_BACKOFFICE_DOC_URL |
the back-office documentation |
APP_STRATEGY_URL_EN, APP_STRATEGY_URL_FR |
the climate strategy page |
Optional values. An empty value hides the link that uses it.
- Access tool:
APP_ACCESS_MANAGEMENT_URL,APP_ACCESS_MANAGEMENT_ABOUT_URL,APP_ROLES_DOC_URL. The oldAPP_ACCESS_MANAGEMENT_PROVIDER_NAMEgoes away: no value names the tool. - Sources:
APP_SOURCE_CODE_URL,APP_USER_DOC_SOURCE_URL,APP_BACKOFFICE_DOC_SOURCE_URL,APP_DEVELOPER_DOC_URL. - Operations:
APP_OPS_ARGOCD_URL,APP_OPS_GRAFANA_DASHBOARD_URL,APP_OPS_GRAFANA_GRAPHS_URL,APP_OPS_LOGS_URL,APP_OPS_OPENSHIFT_URL.
Two values lose their EPFL default. If APP_MATOMO_SITE_ID is set,
APP_MATOMO_URL is required. If APP_DEMO_MODE is true,
APP_PRODUCTION_URL is required. The planner years
APP_PLANNER_MIN_YEAR and APP_PLANNER_MAX_YEAR lose their chart default
and are required. An institution gives them in values.env, and a chart
default in the environment replaces a value of that file. For the same reason,
APP_ENVIRONMENT and APP_DEMO_MODE keep their chart default and are
refused in values.env. The backend loses its defaults for DB_URL
and FRONTEND_URL. The Helm default of FRONTEND_URL is empty, so a
cluster that does not set it stops at boot. Docker Compose does not read
backend/.env: it reads backend/.env.example and gives the backend a
fixed DB_URL for its own postgres service. So a backend/.env that
names a shared database never gets the migrations of a local
docker compose up.
The texts add page paths after APP_USER_DOC_URL and
APP_BACKOFFICE_DOC_URL. If one does not end with /, the container
stops with the reason.
If APP_EQUIPMENT_POWER_FEEDBACK_EMAIL is empty, the equipment dialog has
no power request tab: a mailto link without a recipient opens an empty
draft.
The values can come from the optional file values.env of the
institution folder, from the environment of the pod, or from both. If
/institution/values.env exists, entrypoint.sh reads it in the
container. Then the script reads the environment. A variable of the
environment wins over the file. So a deployment can keep its institution
values in values.env. It sets the per-cluster values under the Helm
frontend.env: APP_ENVIRONMENT, APP_SENTRY_DSN, APP_MATOMO_* and
APP_OPS_*. The file holds
APP_<NAME>=value lines, # comments and literal values. Any other line
stops the script.
The dev server, the tests and Storybook read one variable,
INSTITUTION_DIR: a path relative to frontend/, or absolute. If it is
not set, they use frontend/institution-example/ ("Example University").
So a new clone runs with make install alone, which copies no
institution file. To see a real institution, a developer sets
INSTITUTION_DIR in frontend/.env.local. A personal APP_* value in
.env.local still wins. build/institution.mjs loads .env.local for
quasar dev and for npm run preview, with process.loadEnvFile of Node.
The dev server gives the output folder of the script to Vite as its public
folder. Vite then serves /injectEnv.js, /theme.css and /institution/
as nginx does. If a file of the institution changes, the dev server runs
the script again and reloads the page.
Three builds outside the container write the institution files with the
same script. npm run preview and the Lighthouse workflow run
build/prepare-preview.mjs on dist/spa. The Storybook image copies the
example folder from its normal build context frontend/.
Texts¶
The English and French texts hold placeholders, for example
%institution%. When src/i18n/index.ts builds the messages, it
replaces the placeholders with the values (src/utils/i18nPlaceholders.ts).
It escapes the characters that vue-i18n reads as syntax (@, {, },
|, $). An unknown placeholder throws. The message functions of
common.ts hold no placeholder and stay as they are.
| Placeholder | Value |
|---|---|
%institution% |
APP_INSTITUTION_NAME |
%institution_fr_de% |
APP_INSTITUTION_NAME_FR_DE |
%institution_fr_a% |
APP_INSTITUTION_NAME_FR_A |
%institutional_id% |
APP_INSTITUTIONAL_ID_LABEL |
%contact_email% |
APP_CONTACT_EMAIL |
%user_doc_url% |
APP_USER_DOC_URL |
%backoffice_doc_url% |
APP_BACKOFFICE_DOC_URL |
%strategy_url% |
APP_STRATEGY_URL_EN in English, APP_STRATEGY_URL_FR in French |
The doc links keep their page path after the placeholder, for example
%user_doc_url%fr/headcount/.
No text names Accred, for every institution. The texts say "the access management tool" and "the units directory".
The French forms give a straight apostrophe ("de l'EPFL"). A few texts had a typographic one before. There is no "pour" form: one text now says "de référence de l'EPFL" instead of "de référence pour l'EPFL".
Assets folder¶
The deployment mounts its folder at /institution. At startup,
frontend/docker/entrypoint.sh copies the defaults of the image to
/tmp/institution. The defaults are frontend/institution-default/, in
the image at /usr/local/share/institution/default. Then the script
copies the files of the mounted folder on top. nginx serves
/tmp/institution at /institution/. A second
Content-Security-Policy stops script in a file that a browser opens as
a page, for example an SVG of the institution.
Each font has a second, versioned name, for example
font-bold.1879745468.woff2, with the cksum of its content. That
content never changes, so browsers keep the file one year, and
theme.css points at it. The fonts are about 55 KB of the folder. The
other files keep their fixed name and are revalidated on each use. A
versioned logo was measured and rejected. The login preloads need its URL
before the app starts. So injectEnv.js had to load synchronously, and
that added 150 to 200 ms to the simulated first paint of the login page.
The script also sets the time of each written file from its checksum.
nginx builds the ETag from the file time and the size, so every pod
and every restart give the same ETag for the same content. Without
this, each pod start gave new validators, and a browser that reached
another pod downloaded every file again.
The files:
values.env (optional, see Values)
logo.svg
login-illustration.svg
favicon.ico
favicon-16x16.png favicon-32x32.png favicon-96x96.png favicon-128x128.png
font-regular.woff2 font-medium.woff2 font-bold.woff2
theme.conf (required, no default)
The defaults are a gray mark with a leaf for the logo and the icons, the
login illustration in gray, and Geist. The log gives the source of each
file. These cases stop the container with a message: no theme.conf, an
empty file, a file name outside the list, and a subfolder. The folder is
flat because a ConfigMap key cannot contain /. A flat folder mounts from
a ConfigMap, a Helm chart, a Docker volume or a local path with no special
case. Names that start with . are skipped, because a ConfigMap mount
adds ..data. A file with a name that starts with font- and does not end
with .woff2 is allowed and not copied. A free font keeps its license
next to its files, for example font-license.txt. A line of theme.conf
can end with \r\n.
The default fonts are Geist 1.3.1 under the SIL Open Font License.
pyftsubset keeps Latin-1, the usual punctuation, €, − and ₂.
frontend/institution-default/font-README.md gives the licensing rules
and holds the license text. The license of the EPFL brand font Suisse
Int'l does not allow it in a repository. The license of a system font such
as Arial does not allow it either.
The example folder frontend/institution-example/ holds only
values.env and theme.conf, so the dev server, the tests and Storybook
run on the default assets. Docker Compose mounts it at /institution and
has no institution env_file. The Helm chart mounts the volume
that frontend.institutionAssets.volume gives, and fails to render
without it, because the volume gives theme.conf.
Each render of the chart in the repository gives a volume name. The
renders are the smoke render of the deploy pipeline (.gitlab-ci.yml),
the checks of helm/Makefile and helm/examples/values.yaml. For the local cluster,
the Skaffold chart makes the ConfigMap from the example folder, through
the symlink helm/skaffold/institution.
Theme¶
theme.conf has one name: value line per value. A line that starts
with # is a comment. frontend/docker/entrypoint.sh writes theme.css
with one --theme-<name> property per line. A value is pasted into CSS, so
each kind of name accepts one shape, and every other value stops the
startup. A color is a hex value (#rgb or #rrggbb, with or without
alpha). A radius is a number with px, rem, em or %. An unknown name
and a line without : also stop the startup. The message gives the line
number. Only accent is required. The names are listed in entrypoint.sh,
and frontend/institution-default/theme.conf.example documents each one.
scripts/check-theme-keys.mjs makes sure that the SCSS uses the same
names.
font-regular, font-medium and font-bold take the URL of a woff2 file:
an https:// URL or a path that starts with one /. entrypoint.sh
writes one @font-face rule per weight for the family InstitutionFont, because
@font-face cannot read a custom property. Without a value, the rule loads
/institution/<name>.woff2, for example /institution/font-bold.woff2. The bundle has no @font-face rule,
and index.html preloads no font, because the URLs are known only at
startup.
The shades of the accent (accent-hover, accent-light,
accent-lighter) default to a color-mix() of the accent. A theme can
set them, and the EPFL theme does, so EPFL keeps its exact colors.
Removed¶
GET /v1/unit/{unit_id}/resultsand the fixed EPFL answer it returned, with the unused unit-results state of the workspace store.- The
epfl-logo.svgimport, theenac-it-fonts.epfl.chfonts of the bundle and the font preloads. EPFL gets the same fonts through itstheme.conf. src/css/00-fonts/_fonts.scssand thefontsCSS layer.- Unused texts
header_documentation_linkandheader_dev_documentation_link. src/constant/institutionalId.ts. The label is a value now.frontend/public/injectEnv.js. nginx and the dev server serve it.- The missing-values page and its checks in
src/config/runtime.ts. The container checks the values at startup.
Renamed¶
ReductionObjectiveEpflView.vueis nowReductionObjectiveInstitutionView.vue. The textsresults_objectives_*epfl*are nowresults_objectives_*institution*.- The font family
SuisseIntlis nowInstitutionFont. - The seed input file
reduction_obj_epfl_footprint(in).csvis nowreduction_obj_institution_footprint(in).csv. The file is not in git: each developer renames the local copy inbackend/INPUT_DATA/.
CI check¶
If a file that git tracks or does not ignore has EPFL, epfl, Accred,
ACCRED or Entra, scripts/check_institution_words.py fails. make
lint runs it, and the job institution-words of quality-check.yml runs
it on each pull request. It skips the documentation (docs/, *.md).
scripts/institution-words-allowlist.txt lists the exceptions, each with
a reason:
- the GitHub organization and the image registry of the project
- the CI/CD and team tooling of the project repository
- the immutable Alembic history
- the Accred and Entra words of the backend login and units, and the Accred secrets of the Helm chart, which #3246 removes
EPFL_TABLEAU, which #3245 renames
EPFL deployment (ops repository)¶
The ops repository changes first, and this branch lands after it. The new
image stops without the nine required values and the assets volume. The
image of today ignores a value that it does not know, so the new values are
safe to add early. The three old APP_ACCESS_MANAGEMENT_PROVIDER_* values
stay until the new image runs, then a second change deletes them.
Before the next deployment, a human changes the ops repository:
- Rename
APP_ACCESS_MANAGEMENT_PROVIDER_URLtoAPP_ACCESS_MANAGEMENT_URL. - Rename
APP_ACCESS_MANAGEMENT_PROVIDER_ABOUT_URLtoAPP_ACCESS_MANAGEMENT_ABOUT_URL. - Delete
APP_ACCESS_MANAGEMENT_PROVIDER_NAME. - Take the EPFL folder from its own repository,
EPFL-ENAC/co2-institution-epfl. It holdsvalues.env,theme.conf, the logo and the icons, and it publishes them as a Helm chart. The ops repository holds no copy of these files. - Install that chart in each overlay, next to the
co2-calculatorchart. - Keep the per-cluster values (
APP_ENVIRONMENT,APP_SENTRY_DSN,APP_MATOMO_*,APP_OPS_*) in the overlays, underfrontend.env. - Set
APP_MATOMO_URLandAPP_PRODUCTION_URLwhere they are used. - Give the ConfigMap of the chart to
frontend.institutionAssets.volume. Its name is fixed, and the chart version is a label. The frontend reads the folder only at startup. So each overlay has a kustomize replacement that copies that label into theinstitution-versionannotation of the frontend pods. A new chart version is then one edit, and it restarts the pods. - Keep in the overlay each value that the image of today reads, until the
new image runs. That image cannot read
values.env. - Set
FRONTEND_URLandDB_URLfor the backend. They have no default.
A developer also adds FRONTEND_URL to backend/.env. To see EPFL
locally, a developer sets INSTITUTION_DIR to the EPFL folder.
Caveats¶
- The first-load badge counts only the bundle. The fonts of the deployment are not known at build time.
- Without the font preloads, the browser finds the fonts only after it
applies
theme.css. That is about 155 ms after the page request, against 36 ms with the preloads (login page, local build, real font server). The first text can show the fallback font a little longer. The first paint does not wait for the fonts, and Lighthouse gives it 1.50 s against 1.96 s before. - The logo is now a file of the deployment, not a part of the bundle. The browser asks for it only after the app starts. The logo of the login page loads eagerly and without a fade. It paints with the first text (149 ms against 148 ms before this change, 294 ms without these settings). The mobile simulation of Lighthouse still counts the logo as the largest paint and gives 4.2 s against 1.96 s, score 86 against 98. With the desktop preset of the nightly job, the score is 99 against 100 (0.94 s against 0.49 s). Three other changes did not move the mobile number, so the branch has none of them: a preload of the logo, a high fetch priority, and the logo in the static page.
- The
institution-wordsjob is a required check only after an admin adds it to the branch protection ofdevandmain. - A change of
theme.confor ofvalues.envreloads the dev server page. A change of.env.localneeds a restart of the dev server. entrypoint.shsends only the names thatsrc/config/runtime.tsreads, and a test keeps the two lists equal. It cannot see a secret in the value of a known name.- A link in the institution folder must stay inside the folder. A Docker or host volume with a link to an outside file stops the container.