You want to download Github Desktop
This installer will automatically install itself when you run it. Once it installs, it will prompt you to login.
Depending on your status of your GitHub account, you might need to enable 2FA
Society-In-Shadow should show up as an organization, Expressed Realms is the name of the repository.
Click on it, click clone, make sure to note where it's be put in the system (2nd text field)
If it doesn't show up, let Cameron know, he'll get you access.
Docker is required to run this application locally.
Download and install Docker Desktop. Follow their instructions to get docker up and running : Install Windows
Once you have their hello world example up and running, you should be good to go.
Use an admin powershell for the following commands.
To Download and install chocolatey:
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))Now run the following to get mkcert locally
choco install mkcertWith that, you need to make sure that you have the appropriate folders, and start executing commands from them.
mkdir -p $env:USERPROFILE\.aspnet\https\
cd $env:USERPROFILE\.aspnet\https\That should get you to that folder in your user profile. If it says the folder already exists, just use the CD command.
Now run these commands
mkcert -key-file key.pem -cert-file cert.pem localhostWhen you visit the sites, both Chrome and firefox will consider the certificates to be invalid, as it doesn't trust local certificates. If you click through it, it should let you in though.
With all of that in mind, we need to go to the repo you downloaded earlier. In the root folder (Same folder as this readme), you need to create a ".env" file. In said file, add this information.
Side Note: Avoid spaces on the right hand side of the values
# pgAdmin is the db management tool.
# These values are your login credentials
PGADMIN_EMAIL=
PGADMIN_PASSWORD=
# This is the db name, plus the user and
# password you need to connect to it
DB_NAME=expressedRealms
DB_USER=
DB_PASSWORD=
# This is predefined with the mkcert command.
# DO NOT modify this
CERTIFICATE_PASSWORD=changeit
# Ask about this key
POSTMARK_API_KEY=
# Global From Email
NO_REPLY_EMAIL=admin@societyinshadows.org
# Email address the admin test email sends to
TEST_EMAIL_ADDRESS=YourEmailAddressHereHot reloading using Vite won't work with docker compose, due to fundamental issue with how WSL works.
See: Broken File Watcher
Fundamentally, since the docker runs it's containers on WSL, when you update something on windows, that update isn't being translated into the linux version of hey a file updated process, thus not vite to pick up the changes.
There are some workarounds, the only one that I could get working is below.
To enable it, though at a cost of CPU run time, add the following to the server portion of vite config
watch: {
usePolling: true
}Once you get docker up and running, and get the environment file in place, you should be good to go to start the website.
What you want to do is open up the root of the project (the same directory as this readme) in powershell, and run the following command.
docker compose upIt will start to do a lot of things. If this is the first run, it will take some time to download stuff.
Once everything has been downloaded, it should start db followed by the vue app. Once the DB is up and running, it will start the web api, then the pgAdmin.
Once the messages cool down, you can visit links below.
NOTE: The front end might take a bit to load, as first load takes a bit.
We use a postgres database. On our locals, that db will be handled by the docker image for postgres.
On first start, the web api will populate the db and fill it in with sample data.
Connection details can be found in the docker-compose.yaml file.
The database will be persistent across the docker images build / rebuild.
If you want to nuke the db, run this command first:
docker volume lsWith that list, there should be a db_data volume
Once you find that, copy it and run this command.
NOTE: this is case sensitive
docker volume rm nameOfVolumeThat name should be fairly consistent going forward, so you won't need to run the first step all the time.
pgAdmin is a postgres database management tool. For Expressed Realms, it runs in a docker container.
When the app is started for the first time, it will create a new directory
You can access here:
When you visit it, it will prompt you for a username and password
To login, take a look at that ".env" file you created, it's the credentials you put there.
Once you get in, you need click add server.
On the popup, there are two tabs you need to be concerned about to get this up and running: General and Connections
For the general tab, only value you really need to be concerned about is the name field, the rest of them you don't need to set
| Field | Value |
|---|---|
| Name | Expressed Realms |
NOTE: Env File variables are case sensitive
| Field | Value |
|---|---|
| Hostname/Address | expressed-realms-db |
| Port | 5432 |
| Maintenance Database | From the env file: expressedRealms |
| UserName | From the env file: DB_User |
| Kerberos authentication? | Don't Enable |
| Password | From the env file: DB_Password |
| Save Password | Enable it |
| Role | Leave Blank |
| Service | Leave Blank |
Hit save, and it should connect.
NOTE: I don't think you can connect to this from a local install of pgAdmin think the hostname would be localhost
To test: On the left hand side,
Right click on that table, and hit view / edit data.
There should be 2 characters in there, John and Jane Doe.
The app uses sendgrid to send emails, locally, it doesn't actually hit the API. Instead it hits a local docker image that is emulating sendgrid.
As a result, messages are not actually sent, they are being stored in that docker image.
The emails can be grabbed from here:
docker compose updocker compose downdocker compose build --no-cachecurl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcertInstall nss-tools to allow the CA to be used in firefox and chrome
sudo dnf install nss-toolsmkcert -install
mkdir ~/.aspnet/https -p
cd ~/.aspnet/https
mkcert -cert-file cert.pem -key-file key.pem localhostSince you use linux, you need to add this to your env file. UserProfile isn't predefined on linux machines like it is on windows
# If you use linux, set this to your home directory
USERPROFILE="/home/<username>"If you get this: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock:
sudo usermod -a -G docker <username>After that log off and back on
You might need to chmod 777 the entire directory and files if you run into permission issues while running Docker
This can happen if you have cypress open, and you try start / stop the docker compose, specifically the vue docker.
All you need to do is close cypress and you should be good to go.
Cypress is configured in this repo. Both the end to end and the component testing is implemented. In order to run it on your local you need to go to the expressedRealms.client folder, and run one of the following commands.
For more inforamtion, see Cypress
When you run the below command, it will pop up a GUI that will allow you to run both types of tests and watch them run. You can only do one or the other. The main benefit here is that you can watch them run, and debug them in place to a degree. The main benefit of using the GUI is that it will update in realtime, as you are modifying the components.
npx cypress openThe following runs the end to end testing via the command line. It does everything the GUI does, it just does it headlessly.
npx cypress runSimilar to the above command, it does everything the GUI does, but headlessly.
npx cypress run --componentYou also might need to use the following command if you try running Cypress Component Testing and Docker at the same time.
You need to be in the expressedRealms.client folder for this to work.
sudo chown -hR <username> node_modules/