krgamestudios/MERN-template
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated tutorial setup (markdown)

Kayne Ruse
2021-03-13 23:53:53 +11:00
parent 27571cc05a
commit b6713b7796
1 changed files with 117 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tutorial-setup.md
+117 -91
@@ -1,84 +1,35 @@
# WARNING: This tutorial is still a work in progress - don't use it!
# Setup Tutorial
Hello! This is the tutorial for setting up the MERN-template. If you haven't already, I recommend you download the MERN-template from here:
Hello! This is the tutorial for setting up a vanilla MERN-template server. If you haven't already, I recommend you download the MERN-template from here:
https://github.com/krgamestudios/MERN-template
Remember: This project isn't ready for deployment yet - it still has bugs galore.
Before we begin, you should know that the MERN-template uses a [microservice architecture](microservices). What this means in practice is that "[Setting Up Deployment](#setting-up-deployment)" will pull a fresh copy of all of the microservices from docker hub, and "[Setting Up Development](#setting-up-development)" will connect to publicly available dev servers that I'm currently providing. You'll need to follow "[Setting Up Locally](#setting-up-locally)" for everything to work locally.
## The What-Template?
## Vanilla?
MERN can stand for a few things, but in this case it means "MariaDB, Express, React and Nodejs". This are a series of technologies commonly used to create websites.
I determined that I might want to reuse some parts of the website I was planning to make, so I wrote the template first, to make it easier to reuse. Then, I released it so other people could use it too.
You're currently reading the tutorial on how to set up the template website, both in development mode and deployment mode. This tutorial will likely evolve over time as the template does - and there will likely be other guides going into how the template is built and how to modify it.
This just means "unedited" or "unmodified". This project is designed to be highly customizable for the average intermediate developer, so they can create their own [PBBG](pbbg).
## Requirements
There are some requirements for this template, such as required software and a dedicated email. Software needed includes:
Familiarity with at least some of these technologies is a great advantage when using this template.
* Git
* React
* Nodejs
* MariaDB
* Docker
* docker-compose
* MariaDB (and Sequelize)
* Docker (and docker-compose)
You'll also need an email address - if you use google, you'll need to enable "[less secure apps](https://support.google.com/accounts/answer/6010255?hl=en#zippy=%2Cif-less-secure-app-access-is-off-for-your-account%2Cif-less-secure-app-access-is-on-for-your-account)" so external apps can access it. I've only used this site with google so far, but feel free to experiment with other mail hosts.
You'll also need an email address (if you use google, you'll need to enable "[less secure apps](https://support.google.com/accounts/answer/6010255?hl=en#zippy=%2Cif-less-secure-app-access-is-off-for-your-account%2Cif-less-secure-app-access-is-on-for-your-account)" so external apps can access it). I've only used this site with google so far, but feel free to experiment with other mail hosts. What's important is that you have their SMTP's web address.
## Setting Up Development
For development, you'll need Nodejs and MariaDB installed and working. Remember to run `npm install` in the git repo after cloning.
First, run `sql/create_database.sql` on your mariaDB instance - this will create a database called `template` and a user called `template`@`%`. You can of course mess with this, but everything else here assumes you do so consistently.
Next, copy `.envdev` into `.env`, then fill out `.env` with your details. Here's a breakdown of each field and what they mean:
For deployment you'll also need a server (such as those provided by [linode](https://www.linode.com/)), and a domain name pointing at that server. Add some "A records" to your domain's DNS records such as "news" and "auth" which point to the same server as the main record. You'll need to add a TXT record to your DNS as well, for the domain "auth":
```
WEB_PROTOCOL=http # are you using HTTP or HTTPS?
WEB_ADDRESS=localhost # what is your web domain?
WEB_PORT=3000 # what port is the game running on?
"v=spf1 a ~all"
```
The first two are used mainly for the email validation link at the moment - but they should still be configured correctly. `WEB_PORT` is used to specify which port the game operates on - when you reach the webpack stage, you won't access this port directly.
This is primarily so the auth server can send emails to validate user email addresses (if you use linode as I suggested, you'll have to open a support ticket to allow your user account to send emails via the email ports. This is linode's restriction against spammers).
```
MAIL_SMTP=smtp.example.com # SMTP server
MAIL_USERNAME=foobar@example.com # Email to be used
MAIL_PASSWORD=foobar # Password of that email account
MAIL_PHYSICAL=42 Placeholder Ave, Placeholder, 0000, USA # Your physical mailing address
```
Now, I've use exclusively google for this - and it shows. The first argument is usually set to `smtp.gmail.com`. The second is to your email account (a fake one is set in the code, `signup@WEB_ADDRESS`, but google overwrites this). The third is the plaintext password for this account (so you should almost certainly use a dedicated email for this). The fourth is actually included in the validation email itself - it's a legal requirement of the USA's [CAN-SPAM](https://en.wikipedia.org/wiki/CAN-SPAM_Act_of_2003) act of 2003, which goes over my head just a little (I try to appease as many jurisdictions as possible).
```
DB_HOSTNAME=127.0.0.1 # Database address
DB_DATABASE=template # database name
DB_USERNAME=template # database user
DB_PASSWORD=pikachu # database password
DB_TIMEZONE=Australia/Sydney # database timezone
```
This is fairly simple - but if you tinkered in `sql/create_database.sql`, do so here as well. `127.0.0.1` just means "this machine", of course. The timezone is my own timezone, but can be set to [any of these values](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (I think - haven't tested them).
```
SESSION_SECRET=secret
SESSION_ADMIN=adminsecret
```
Finally, these are crucial in production - so much so that they're completely randomized by the configure script. Here, however, you can set them to anything. `SESSION_SECRET` is used by `express-session` to save user session details, while `SESSION_ADMIN` is used as a sort of password for the administrator accounts.
Finally, it's time to run `npm run dev`. This will begin the server in dev mode - it'll use the `concurrently` library to run both client and server in the same window, so you don't need two monitor terminals. If all goes well, the server should start pretty quickly, though the client will take a moment to compile.
When they're both ready, you can access `http://localhost:3001/` in a browser (NOT 3000) and the template site should load.
At this stage, your brand new website will call out to the `dev-news` server for news postings, so you'll get some lorem ipsum, and possibly other content (it's a publicly available server - don't blame me!).
The server should've created a default administration account (and outputted the email and password). By logging in with this, you can access `http://localhost:3001/admin` and post to or edit existing news posts.
From here, you can now start exploring and fiddling with the code. Feel free to contribute any changes via pull requests on github; I'm likely to accept them if they improve the overall experience. Even these docs (and this tutorial) are subject to updates, so check back if you need to.
Depending on your jurisdiction, you'll also need a physical mailing address (blame America's [CAN-SPAM](https://en.wikipedia.org/wiki/CAN-SPAM_Act_of_2003) act).
## Setting Up Deployment
@@ -86,56 +37,131 @@ In a perfect world, deploying to a server would be as easy as:
```
git clone https://github.com/krgamestudios/MERN-template.git
npm run configure
node configure-script.js
docker-compose up --build
```
Sadly, this isn't a perfect world. So let's instead break down what I did for the tentative deployment.
Surprisingly, once you've installed git, nodejs, docker.io via your favourite package managers (and docker-compose via [various methods](https://docs.docker.com/compose/install/)) you'll be able to run things pretty easily.
First, you'll need a server with a domain name. I personally pointed both `dev.eggtrainer.com` and `news.eggtrainer.com` at the same server (You might be able to separate the news server later - that's why there's two URLs). I'm using linode for this, but be aware that linode blocks email access until you open a ticket requesting permission to use emails from their servers. It's easy - just don't abuse their goodwill. I ended up using debian as the OS, but anything that runs node and docker should work.
HOWEVER configure-script.js does do some heavy lifting before docker-compose - it generates three files:
Then, I installed git, node (for npm) and docker-compose on the new server. Then I cloned the MERN-template into the server. Note that I didn't install mariaDB or run `npm install` - docker-compose handles these.
```
docker-compose.yml
Dockerfile
startup.sql
```
Next I ran `npm run configure`, which takes in a number of arguments and spits out a number of config files. Here's the default prompts:
docker-compose.yml is used by docker-compose, Dockerfile is used for *this repo* specifically, and startup.sql is invoked by the mariaDB container on startup to generate the empty databases. Let's look at the prompts:
```
Project Name (template):
Project Web Address (example.com):
Project Mail SMTP (smtp.example.com):
Project Mail Username (foobar@example.com):
Project Mail Password (foobar):
Project Physical Mailing Address (<empty>):
Project Database Username (template):
Project Database Password (pikachu):
Project DB Username (template):
Project DB Password (pikachu):
News Name (news):
News Web Address (news.example.com):
News Database Username (news):
News Database Password (charizard):
News Query Key (<random>):
News DB Username (news):
News DB Password (charizard):
Auth Name (auth):
Auth Web Address (auth.example.com):
Auth DB Username (auth):
Auth DB Password (venusaur):
Email SMTP (smtp.example.com):
Email Address (foobar@example.com):
Email Password (foobar):
Physical Mailing Address:
Database Root Password (password):
Database Timezone (Australia/Sydney):
Access Token Secret (<random>):
Refresh Token Secret (<random>):
Default Admin User:
Default Admin Pass:
Support Email (foobar@example.com):
```
These should generally be fairly self-explanatory, except the values in the parentheses can changed based on previous entries. If you make a mistake here, just re-run this. This script produces three files:
Some of the default values (those between the parentheses) will change based on previous answers for your convenience.
* docker-compose.yml
* Dockerfile
* setup.sql
For your first deployment, you should stick to the defaults as much as possible. However, you should fill out the following:
`setup.sql` is invoked by Dockerfile to create the database if it doesn't already exist, and `docker-compose.yml` invokes Dockerfile, among a number of other built-in containers (mariaDB and news-server). This will update regularly so check back often. If you want to delete any files created by configure, just run `npm run clean`.
```
Project Web Address (example.com):
News Web Address (news.example.com):
Auth Web Address (auth.example.com):
Email SMTP (smtp.example.com):
Email Address (foobar@example.com):
Email Password (foobar):
Default Admin User:
Default Admin Pass:
```
Finally, it's time to run `sudo docker-compose up --build`. You might actually need to run it several times, killing the first attempts, as I haven't weeded out certain bugs yet. Remember - it's only in alpha, and not ready for prime time just yet.
Be aware that "Email Password" is your plaintext email password, which will be stored in docker-compose.yml. It'll be safe, but generally a good idea not to use your main account for this.
You now have a self-contained MERN-template container, mariaDB container, news-server container and [traefik](https://traefik.io/) container.
"Default Admin Pass" will only appear if "Default Admin User" is set, and the generated login email will be printed to the screen (it'll use the web address for the auth-server such as "admin@auth.example.com"). This is the email address you use to log into the deployed app at first; the auth-server tries to generate this account every time it starts with 0 existing administrator accounts.
Finally, run this to deploy the project:
```
docker-compose up --build
```
You might need sudo, and you could ad `-d` to detach the process from the console. Now, navigate to your main web address, and you should see the empty homepage. If there are any issues, check the [troubleshooting page](troubleshooting).
## Setting Up Development
For development, you'll need Nodejs and MariaDB installed and working on your machine. Remember to run `npm install` in the git repo after cloning to get all of the libraries.
First, run `sql/create_database.sql` on your mariaDB instance - this will create a database called `template` and a user called `template`@`%`.
Next, copy `.envdev` into a new file called `.env`.
Finally, it's time to run `npm run dev` in the console. This will begin the server in dev mode - it'll use the `concurrently` library to run both client and server in the same window, so you don't need two monitor terminals. If all goes well, the server should start pretty quickly, though the client will take a moment to compile.
When they're both ready, you can access `http://localhost:3001/` in a browser (NOT 3000) and the template site should load.
At this stage, your brand new website will call out to the `dev-news` server for news postings, so you'll probably get some lorem ipsum, and possibly other content (it's a publicly available server - don't blame me!). You will also be able to signup and log into the `dev-auth` server, but you won't have administration privileges.
## Setting Up Locally
To set up the microservices locally, you'll first need to download them (probably via git):
* Auth Server: https://github.com/krgamestudios/auth-server
* News Server: https://github.com/krgamestudios/news-server
* Chat Server: https://github.com/krgamestudios/chat-server
*chat-server is not currently working at the time of writing, but included for completeness.*
Each one has it's own `configure-script.js` for independent deployment, but in this case copy the `.envdev` file to a new file called `.env` and fill out each field, ensuring that the line `SECRET_ACCESS` matches between every program (including the MERN-template).
Next, you'll need to open the MERN-template's `webpack.config.js` file, and replace this:
```
new DefinePlugin({
'process.env': {
'PRODUCTION': production,
'NEWS_URI': production ? `"${process.env.NEWS_URI}"` : '"https://dev-news.eggtrainer.com/news"',
'AUTH_URI': production ? `"${process.env.AUTH_URI}"` : '"https://dev-auth.eggtrainer.com/auth"',
'CHAT_URI': production ? `"${process.env.CHAT_URI}"` : '"https://dev-chat.eggtrainer.com/chat"',
}
}),
```
With the following (this point the client at the correct localhost ports, notice the change in HTTP protocol):
```
new DefinePlugin({
'process.env': {
'PRODUCTION': production,
'NEWS_URI': production ? `"${process.env.NEWS_URI}"` : '"http://localhost:3100/news"',
'AUTH_URI': production ? `"${process.env.AUTH_URI}"` : '"http://localhost:3200/auth"',
'CHAT_URI': production ? `"${process.env.CHAT_URI}"` : '"http://localhost:3300/chat"',
}
}),
```
Finally, open a terminal for each project, point it to the project's directory and run `npm run dev`. Once each one reports that they're listening on a specific port, then you can visit the development server at `http://localhost:3001/`.
From here, you can log into the default admin account if you chose to create one, create local accounts and post local news, etc.
## Troubleshooting
**Deploying the project didn't work?**
Try again. There are timing issues between the different containers that I still need to sort out. If it still doesn't work after 5-ish attempts, keep reading.
**Sequelize throws an error that a certain field is missing?**
If you just upgraded the template, try checking if any changes to the sequelize models have occured. If so, you'll have to go into the mariaDB container and alter the database directly.
See the [troubleshooting page](troubleshooting).