Contest Setup Guide

for IT manager

Contest General Steps:

• Make Contest Page
• Make VMs
• Set Cloudflare Subdomain
• Before Contest, Resize Servers

Contest Page

Note about editing and testing:

• When updating page, if not too familiar with HTML, copying usually works; confirm & test via yarn dev before pushing.
• Needs nodeJS and Yarn to test
  • If not, download nvm and corepack enable
  • This installation might run into issues if you already have pieces installed
  • This project uses yarn 3 Steps to test:
• git clone https://github.com/teamscode/teamscode-website
• cd teamscode-website
• yarn
• yarn dev

Files to edit: ‘Content’ pages are defined by markdown files in /content
In /content/contests, copy the latest contest’s file (named spring-2025.md) into a new file named the current contest (summer-2025.md)
Edit information within.
Notes:

• Remove ‘winners’ section
• Change ‘cards’ to divisions, prize value, past participation, teams size
• Edit timeline to the current plan
• Edit ‘status’ to upcoming
• Remove editorials and CF gyms
• Update the contest portal link in rules.md
• Remove ‘participants’

In /content/contests, copy the latest contest’s folder (/content/contests/spring-2025) into a new folder named the current contest (summer-2025)
Edit sponsors.md, prizes.md, and speakers.md

Updating Routing & Buttons:
Links that direct to the contest portal (e.g. spring25.teamscode.org) must be updated
Tip: Command F on last contest's name ('spring25')

• Front page button: index.vue
• Contest portal links on contest page: /contest/_slug.vue
• Might want to disable 'Youtube Livestream' button (by adding disabled in the element in /contest/_slug.vue)

Portal VM

Start VM: Azure Portal

• Create a subscription
• Create a VM
  • x64
  • Ubuntu
  • Dasv5, 2 core
  • SSH key
    • username: teamscode
    • use existing public key
      • enter your machine’s public key. how-to
• Get the machine's IP
• Try logging in: ssh teamscode@[ip]
• On azure, use network -> network settings -> create port rule -> Inbound -> Destination ports: Any

Setup HTTPS Certificate:

• Add DNS Record
  • Log into cloudflare
  • Go into 'Teamscode' account
  • Go into 'teamscode.org' domain
  • Select DNS -> Add Record
  • A Type, Name: contest name (summer25), No proxy, TTL: auto
• sudo apt install certbot
• sudo certbot certonly
  • Use option 1: Run an http server locally...
  • When prompted for 'domain name' use: contest protal domain (e.g. summer25.teamscode.org)
  • Make note of where it stored the certificate
  • Should be something like: /etc/letsencrypt/live/summer25.teamscode.org/fullchain.pem

Start Contest Portal:

• Install docker
• git clone https://github.com/teamscode/portal-deploy.git
• cd portal-deploy/portal-backend
• Edit in services -> backend -> volumes
  • Change the pathes indicating where the certificates are to where the new certificates are
• There is a bug in how the docker image creates files. manually change /data/backend/ssl/server.crt and /data/backend/ssl/server.key to files instead of directories.
• sudo docker compose up -d
  • -d tag runs it as daemon. If its not working, run it without the -d tag, and check what the error logs say.

Controlled Backend Releases

Pushing contest-portal's main branch automatically rebuilds the mutable quay.io/teamscode/contest-server:latest tag. Production must not follow that tag automatically. The compose file defaults to the currently deployed immutable digest, and Watchtower only considers containers explicitly opted in with its enable label. The backend is explicitly excluded.

Before pushing a portal change, deploy the Watchtower safety configuration on the portal VM and verify it is running:

git pull --ff-only
test -e .env || cp .env.example .env
sudo docker compose up -d --no-deps --force-recreate watchtower
sudo docker inspect watchtower --format '{{json .Config.Env}}'

The inspected environment must contain WATCHTOWER_LABEL_ENABLE=true and WATCHTOWER_CLEANUP=false. Do not push the portal change until this is true on the production VM.

After the portal image has built and its exact digest has passed smoke tests, promote it deliberately. In the production VM's ignored .env file, replace CONTEST_SERVER_IMAGE with the complete immutable reference reported by Quay:

CONTEST_SERVER_IMAGE=quay.io/teamscode/contest-server@<tested-manifest-digest>

Then reconcile only the backend and verify the exact image reference:

sudo docker compose up -d --no-deps backend
sudo docker inspect backend --format '{{.Config.Image}} {{.Image}}'
sudo docker compose ps

The backend entrypoint runs database migrations before starting the web server, so a single-instance promotion causes a brief outage. Before promoting a build that contains migrations, take a PostgreSQL backup and confirm that the previous application image remains compatible with the migrated schema.

To roll back application code, put the previous known-good digest back in .env and repeat the backend reconciliation command. Watchtower cleanup is disabled so deliberately managed images are retained, but always record the previous digest before promotion. A code rollback does not reverse database migrations.

Test:
Navigate to the machine's IP via browser and test out the website: Root account is:

• username: root
• password: rootroot
• Change the password after you log in, root -> management -> General -> User -> Edit button on the right side of the user

Portal Setup:

• Turn on API keys (it's a toggle buttons somewhere on the portal)
• Configure mail
  • SMTP Server: smtp.gmail.com
  • Port: 587
  • Username: Your teamscode email. NOTE: your email account needs 2FA enabled in order for google to allow SMTP routing via this account. Turn 2FA on via "manage my account" in gmail.
  • Password: You'll need to create an 'app password' for this app to access your email account. See how here
  • Use the 'send test email' to confirm

Make Judger VM

Start VM:

• Create a second VM
  • Same configurations as above
  • Ensure the two services share the same network
    • in "Networking", "Virtual Network" should be set to the same one as the portal (e.x. portal-vnet)

Start Judger:
Once logged in,

• Install docker
• git clone https://github.com/teamscode/portal-deploy.git
• cd portal-deploy/portal-judger
• Edit docker-compose.yaml:
  • SERVICE_URL: set [THIS_MACHINE_IP] to this machine's private IP address (found via azure portal)
  • BACKEND_URL: set [BACKEND_IP] to portal VM's private IP address
  • RSYNC_MASTER_ADDR: set [BACKEND_IP] to portal VM's private IP address (10.0.0.4)
• sudo docker compose up -d

Test:
Check on admin, under 'judge server'. It should show a server.

Cloudflare

This manages our ‘teamscode.org’ domain. We need to access this each contest to add the contest sub-domain (the spring25.teamscode.org)

Access Via: dash.cloudflare.com” Log in Via: exec@teamscode.org has access. If others want direct access (since exec is hard to sign in with 2fa), lmk At the dashboard -> account home -> teamscode.org to get into domain dashboard go to DNS -> Add Record Name: the contest name (e.g. summer25, spring26, etc) IPv4 address: Azure contest VM's address