Add guide for setting up on wsl

[Jordan-Cottle]

Summary

As part of getting introduced to this project, I set up teiserver on Ubuntu 22.0.4 from scratch. I did not have WSL set up on PC before, so this guide should cover everything needed from complete 0 to a working teiserver.

I took careful notes about all the steps I needed. Many of these are mentioned in the existing setup guides, but glossed over and not explained in enough detail to help someone who's not familiar with the ecosystem or tools to figure out easily.

Test Evidence

Server running locally in WSL:

Webpage after logging in with root@localhost

[jauggy]

So in this document you created you already have lots of stuff that's already in the local_setup.md so I recommend we just update the original one but add some spoiler sections that you can fill in. See below for example. Update the below example with any extra comments and rearrange any sections if needed. Then overwrite the original local_setup.md

I do wonder if we should move out the config/discord bot stuff to a separate document as they're not needed for local dev.

I tested your Font Awesome commands and they're convenient. Add those too to the relevant section.

[jauggy]

Local/Dev

Clone repo

git clone git@github.com:beyond-all-reason/teiserver.git
cd teiserver

Windows-specific Instructions

It is recommended to install Teiserver on Linux, but if you have Windows then you should install Ubuntu WSL.

Install WSL

Add links to WSL installation and any other comments here

Install Elixir and Erlang

You will need to install Elixir/Erlang. You must use the same versions defined in .tools-versions or you will get errors.

Install Elixir and Erlang using asdf (Recommended)

Add your asdf instructions here

Install build tools (gcc, g++, make)

Ubuntu/Debian

sudo apt update
sudo apt install build-essential

Compile dependencies

mix deps.get
mix deps.compile

Postgres setup

Install Postgres

Add your postgres setup instructions here

Install database

Set up teiserver_dev and teiserver_test accounts:

sudo su postgres
psql postgres postgres <<EOF
CREATE USER teiserver_dev WITH PASSWORD '123456789';
CREATE DATABASE teiserver_dev;
GRANT ALL PRIVILEGES ON DATABASE teiserver_dev to teiserver_dev;
ALTER USER teiserver_dev WITH SUPERUSER;
CREATE USER teiserver_test WITH PASSWORD '123456789';
CREATE DATABASE teiserver_test;
GRANT ALL PRIVILEGES ON DATABASE teiserver_test to teiserver_test;
ALTER USER teiserver_test WITH SUPERUSER;
EOF
exit

Create the database schema for the teiserver application:

mix ecto.create

Localhost certs

To run the TLS server locally you will also need to create localhost certificates in priv/certs using the following commands

mkdir -p priv/certs
cd priv/certs
openssl dhparam -out dh-params.pem 2048
openssl req -x509 -out localhost.crt -keyout localhost.key \
  -newkey rsa:2048 -nodes -sha256 \
  -subj '/CN=localhost' -extensions EXT -config <( \
   printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
cd ../..

SASS

We use sass for our css generation and you'll need to run this to get it started.

mix sass.install

Fake data

Running this:

mix teiserver.fakedata

Will generate a large amount of fake data and setup a root account for you. The account will have full access to everything and the database will be populated with false data as if generated over a period of time to make development and testing easier.

Running it

Standard mode

mix phx.server

Interactive REPL mode (It's the same as standard mode, but allows you to run Elixir commands from the terminal).

iex -S mix phx.server

If all goes to plan you should be able to access your site locally at http://localhost:4000/. There is a default account with email root@localhost and password: password

Libraries you need to get yourself

The site makes liberal use of FontAwesome so if you are using the site you'll need to download it and do the following

fontawesome/css/all.css -> priv/static/css/fontawesome.css
fontawesome/webfonts -> priv/static/webfonts

If you want to use the blog you will also need to place ace.js folder in the same place.

Configuration

Most of the configuration takes place in config/config.exs with the other config files overriding for specific environments. The first block of config.exs contains a bunch of keys and values, which you can update.

Connecting to the spring party of your server locally

telnet localhost 8200
openssl s_client -connect localhost:8201

config/dev.secret.exs

If you want to do things like have a discord bot in development you don't want these details going into git. It is advisable to create a file config/dev.secret.exs where you can put these config details. I would suggest a file like so:

import Config

config :teiserver, Teiserver,
  enable_discord_bridge: true

config :teiserver, DiscordBridgeBot,
  token: "------",
  bot_name: "Teiserver Bridge DEV",
  bridges: [
    {"---", "main"},
    {"---", "promote"},
    {"---", "moderation-reports"},
    {"---", "moderation-actions"}
  ]

# Comment the below block to enable background jobs to take place locally
config :teiserver, Oban,
  queues: false,
  crontab: false

Resetting your user password

When running locally it's likely you won't want to connect the server to an email account, as such password resets need to be done a little differently.

Run your server with iex -S mix phx.server and then once it has started up use the following code to update your password.

user = Teiserver.Repo.get_by(Teiserver.Account.User, email: "root@localhost")
Teiserver.Account.update_user(user, %{"password" => "password"})

Main 3rd party dependencies

The main dependencies of the project are:

• Phoenix framework, a web framework with a role similar to Django or Rails.
• Ecto, database ORM
• Ranch, a tcp server
• Oban, a backend job processing framework.

[Jordan-Cottle]

One reason I wanted a separate document is that this guide is very specific to ubuntu 22.0.4 (and with wsl, dunno if that changed anything though) while the other guide is generic and doesn't specify what OS to use, but is lacking specific instructions because of it.

I also wasn't wanting to disrupt the existing docs, but if we want to update that doc instead I can take a look at doing that

[jauggy]

People actually tried to setup Teiserver on pure Windows and ran into issues. So my recommendation for all future devs on Windows is to use Linux on Windows.

I guess your asdf install instructions are Ubuntu specific and someone else would have to read the docs if they have different distro. Could add that in the spoiler title that it's Ubuntu instructions.