Architecture & Deployment Course Website

This repository contains the source code for the Media Engineering Architecture & Deployment course website, composed of:

• A static site containing most course material, rendered by the application
• A Phoenix application to help students manage a virtual machine in the context of the course
• A Tailwind theme for both parts
• Various related utilities written mostly in TypeScript

• Requirements
• Initial setup
  • Initial Docker setup
  • Initial machine setup
• Run the website in development mode
  • Run in development mode with Docker
  • Run in development mode on your machine
• Configuration
• Credits

Requirements

To run with Docker (slower, but simpler):

• Docker 🎉

To run on your machine:

• Elixir 1.19.x
• Erlang/OTP 28.x
• Node.js 24.x
• PostgreSQL 17.x
• ssh-keygen to generate a key pair

Use asdf or mise to install Elixir, Erlang/OTP & Node.js based on .tool-versions.

Other optional tools (useful in both modes):

• direnv to quickly run scripts

Initial setup

Setup instructions to perform before running the website for the first time.

Initial Docker setup

No setup is required if you have Docker installed. Simply clone the repository.

# Clone this repository.
git clone git@github.com:ArchiDep/website.git
cd website
# Generate an SSH key pair, copy the printed public key.
./scripts/init-docker
# Copy (and adapt) the environment file. (Don't forget to paste the public key# in there.)
cp .env.sample .env

Tip

Optionally, install direnv to automatically have all the project's utility scripts in your PATH when you navigate to the repository.

direnv allow # see .envrc

Initial machine setup

Once you have all the requirements installed, follow these instructions to set up the website to run in development mode on your machine.

You will need a PostgreSQL database. You can either let the website create it if you provide credentials that have sufficient privileges, or create it yourself beforehand.

# Clone this repository
git clone git@github.com:ArchiDep/website.git
cd website
# Install tooling
npm ci # grab a coffee# Build the app assets, course assets & theme at least once
npm run --workspace app build
npm run --workspace course build
npm run --workspace theme build
# Install and compile the Phoenix application's dependenciescd app
mix deps.get
mix compile # grab another coffee (extra large mug)
mix ua_inspector.download --force # user agent database# Copy (and adapt) the application's local config file. Don't forget to set up# the PostgreSQL connection information.
cp config/local.sample.exs config/local.exs
# Create required directories
mkdir -p priv/ssh priv/uploads
# Generate an SSH key (with no password)cd priv/ssh
ssh-keygen -t ed25519 -f id_ed25519 -C archidep
cd ../../
# Perform initial setup (create the database, run migrations, etc)
mix setup

Run the website in development mode

How to run the website in development mode with live reload on code changes.

Run in development mode with Docker

./scripts/dev # or simply "dev" if you have direnv

Tip

It will take a while (quite a long while the first time). The various Docker containers only start when their dependencies have finished their initial run, as defined by their health checks. The startup order is as follows:

• Install the dependencies and fetch the finished editions of the course (archives container, a ~160 MB clone the first time and deltas after that)
• Start the database (db container), compile the application assets (app-assets container), course assets (course-assets container, takes a while to perform the first build) & theme (theme container)
• Start the application (app container)

Visit http://localhost:42000 once the application has started. The app container renders the course material itself and serves what it rendered, so editing a document under course/ rebuilds the site and reloads the browser.

This repository holds one edition of the course material, so the editions that came before it are fetched rather than rendered: they are published as a repository of their own, cloned into tmp/course_site_archives, and served behind the build the way production's static server serves them behind the build the application renders into its document root.

Run in development mode on your machine

Run all of these in parallel:

# Build and watch app assets with esbuildcd app
npm start
# Build and watch course assets with Webpackcd course
npm start
# Build and watch the CSS theme with Tailwindcd theme
npm start
# Run the Phoenix web applicationcd app
mix phx.server

Visit http://localhost:42000 once all tasks have finished starting. The Phoenix application renders the course material itself and serves what it rendered, so editing a document under course/ rebuilds the site and reloads the browser. Start it after the asset watchers, since the first build reads what they write into app/priv/static; ArchiDep.CourseSiteWatcher.rebuild() from IEx runs one by hand if it was too early.

The editions that came before are read from the same tmp/course_site_archives the Docker workflow fills, so a machine-native run shares that clone. Nothing fills it here: ./scripts/dev does, or by hand, git clone --depth 1 https://github.com/ArchiDep/archidep.github.io.git tmp/course_site_archives. Until it is filled the application logs which editions it cannot serve and the admin console says so.

Configuration

These ports are used:

• 42000 (app, main entrypoint)
• 42003 (Prometheus metrics at /metrics)

Concerning the monitoring metrics available at http://42003/metrics, note that in development, the metrics are only updated after 10 minutes and then every 10 minutes by default to avoid polluting the logs with database queries. Update metrics_polling_interval in your config/local.exs file to change this interval (only supported when running on your machine for now).

Credits

The site's emoji are Twemoji by the Twemoji contributors, licensed under CC-BY 4.0.