Setup

Whilst this repo contains some quite daunting moving parts, our Docker setup and build tooling should make setup relatively straightforward. The two things you'll need to install are

• NodeJS
  • Installing via Volta is recommended
• Docker Compose V3.8+

You also need Git, along with a terminal that you're comfortable using.

Please note, some scripts may require Unix-like coreutils such as rm, ls, cd etc. We do not use rimraf. If on Windows, the easiest thing to do is install Git Bash along with Git for Windows.

Cloning

First clone this repo with

git clone https://github.com/momentum-mod/website.git --recurse-submodules

--recurse-submodules is crucial, we submodule in a small shared styling repo that must be cloned for the frontend to build. If you need to pull in any submodule changes (fairly rare), run

git submodule update --init --recursive

(You may also want to set up a custom git upsub alias for this with git config --global alias.upsub "submodule update --init --recursive")

Environment Variables

In the website directory copy the env.TEMPLATE to the same directory, rename it .env, and then add your configuration.

Only STEAM_WEB_API_KEY needs to be updated for basic development. This is an API key granted by Steam at https://steamcommunity.com/dev/apikey, just sign register with localhost as the domain.

Docker will expose the ports of several containers, if using the default passwords in the env.TEMPLATE file, you should not be forwarding them to the Internet.

Docker

We use Docker to handle major services required by the backend. Currently, these are

• PostgreSQL - a relation database
• MinIO - an S3-compatible object (file) store

Our Docker Compose setup is configured to handle these for easy development. Simply run:

docker compose up -d

That will pull images for the services and start them up in containers. Note, if you wish to run these locally you can, but is OS-dependent. Just make sure to configure the services with settings corresponding to those in env.TEMPLATE.

Node

Next, install Node dependencies with

npm install

This will install dependencies for all projects in the monorepo, so is quite sizable (~1.1GB at time of writing). It will also establish commit hooks, which will perform formatting and linting after commits, and generate a copy of the Prisma client, which is essentially a set a type definitions mapping to the database schema.

Additionally, as we will be using Nx for our command execution, it's easiest to install globally with

npm install -g nx

Alternatively, you can skip the global install and just preface every nx command here with npx, e.g. npx nx serve frontend.

Running Applications

Database

We should have a running Postgres database and Prisma installed, so lets push our schema to the database, using

nx run db:push

Additionally, if you want to populate the database with mock data (good if you're doing frontend work), run

nx run db:seed

Backend

Now we'll bring up the backend with

nx serve backend

Note: Here we're using the nx <task> <project> shorthand, which is equivalent to nx run <project>:<task>.

For a quick guide to the Nx CLI see, https://nx.dev/core-features/run-tasks#running-tasks. For a general reference, see https://nx.dev/reference/commands.

This will compile and launch Nest, after which it'll serve endpoints are http://localhost:3000/. Swagger documentation (which was just autogenerated from the backend source) is available at http://localhost:3000/docs.

Authenticating

The majority of the API is locked behind auth, so to query endpoints through Swagger's (or cURL, Hoppscotch, Postman etc.) you'll need a Steam auth token.

Unfortunately this process is a little complicated: our OpenID strategy means we cannot send the token back in a body, and for security reasons we don't include it in the redirect URL, so we send it as a cookie.

So, navigate to http://localhost:3000/auth/web and login via Steam. This will set an accessToken cookie for the localhost domain in your browser. You can access it through browser tools (in Chrome dev tools, you find this in _Application > Storage > Cookies), or alternative use this Tampermonkey script.

Insert that in the "Authorize" dialogue in Swagger, or as the bearer token in your HTTP client. Requests to the API should now work (as in, not 401), with anything specific to your user (e.g. /user/* endpoints) using your actual Steam info!

Frontend

Launching the frontend is simple, just run

nx serve frontend

and navigate to http://localhost:4200.

To build for production, run:

nx build frontend

serve runs in development by default, build in production. For more control do e.g. nx run frontend:build:dev

Other Commands

For running tests, see Testing.

To auto-format your changed code, run

nx format

Our CI enforces that the main branch always conforms to the Prettier config, so this should in effect format just your changes. Note that commit hooks will do this for you on commit anyway.

To lint a single project use

nx lint <project>

However it's generally much easier to run

nx affected -t lint

to just lint projects that have been changed by your branch.

Finally, some packages have custom targets, especially db:

• nx run db:generate: Generates Prisma client from schema. This is run after npm install so you don't need to run unless you've changed the schema
• nx run db:push: Pushes the prisma.schema schema to Postgres. Also runs generate!
• nx run db:seed: Seeds the running database with mock data
• nx run db:studio: Starts a minimal database viewer in your browser. This saves having to connect an external program.
• nx run db:makemeadmin: Makes any user with a real Steam account an admin. You must login to the site at least once to generate a User entry for this to work. Migrate commands will come in the near future.