-
-
Notifications
You must be signed in to change notification settings - Fork 8
tutorial setup
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
Before we begin, you should know that the MERN-template uses a microservice architecture. What this means in practice is that "Setting Up Deployment" will pull a fresh copy of all of the microservices from my docker hub, and "Setting Up Development" will connect to publicly available shared dev services that I'm currently providing. You'll need to follow "Setting Up Locally" for everything to work locally.
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, or other kind of website.
Familiarity with at least some of these technologies is a great advantage when using this template.
- React
- Nodejs
- MariaDB (and Sequelize)
- Docker (and docker-compose)
You'll also need an email address (if you use Google, which is recommended, you'll need to enable "less secure apps" 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.
Update: Google has recently removed the ability to use plaintext passwords with less secure apps enabled - read the link above for more information on how to generate an "app password".
For deployment you'll also need a server (such as those provided by Digital Ocean), and a domain name pointing at that server (domain names can be obtained from registrars such as Squarespace). Add some "A records" to your domain's DNS records such as "news", "auth" and "chat" 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":
"v=spf1 a ~all"
This is primarily so the auth-server can send emails to validate user email addresses.
Update: Due to various changes by my registrar and server hosts, exactly how you obtain a server and a domain name may be different now from how I first did it - some testing is still needed.
Depending on your jurisdiction, you'll also need a physical mailing address (blame America's CAN-SPAM act).
In a perfect world, deploying to a server would be as easy as:
git clone https://github.com/krgamestudios/MERN-template.git
cd MERN-template
node configure-script.js
docker-compose up --build
Surprisingly, once you've installed git, nodejs, docker.io via your favourite package managers, you'll be able to run things pretty easily.
HOWEVER configure-script.js does do some heavy lifting before docker-compose - it generates three files:
docker-compose.yml
Dockerfile
startup.sql
docker-compose.yml is used by docker-compose, Dockerfile is used by docker 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 DB Username (template):
Project DB Password (pikachu):
News Name (news):
News Web Address (news.example.com):
News DB Username (news):
News DB Password (venusaur):
Auth Name (auth):
Auth Web Address (auth.example.com):
Auth Reset Addr (example.com/reset):
Auth DB Username (auth):
Auth DB Password (charizard):
Email SMTP (smtp.example.com):
Email Address (foobar@example.com):
Email Password (foobar):
Physical Mailing Address:
Chat Name (chat):
Chat Web Address (chat.example.com):
Chat DB Username (chat):
Chat DB Password (blastoise):
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):
Some of the default values (those between the parentheses) will change based on previous answers for your convenience.
For your first deployment, you should stick to the defaults as much as possible. However, you should fill out the following:
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):
Chat Web Address (chat.example.com):
Default Admin User:
Default Admin Pass:
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 password for this.
"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 add -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.
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 tools/create_database.sql on your mariaDB instance - this will create a database called template and a user called template@% with the password pikachu.
Next, copy .envdev into a new file called .env (SECRET_ACCESS should have the value access, this is the key for the dev-services that you're about to connect to).
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. Once you sign up and log into dev-auth, you'll have access to dev-chat which will appear as a small window in the bottom right of the screen.
To set up the microservices locally, you'll first need to download them (via git):
- News Server: https://github.com/krgamestudios/news-server
- Auth Server: https://github.com/krgamestudios/auth-server
- Chat Server: https://github.com/krgamestudios/chat-server
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 service (including in MERN-template).
Finally, open a terminal for each project, point it to the project's directory and run npm run dev (or npm run local for the MERN-template). Once each one reports that they're listening on a specific port (or when the MERN-template says it's finished compiling), then you can visit the local servers 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.
See the troubleshooting page.