How to Setup a town
WARNING : DISCMAILER
You need to understand all step, this is just a guide line, do not try to set up a production server if you don't understand linux securities subjects. To make works an apXtrib you need to delegate root privilege to a safe user so be aware. But feel free to play on a dev machine.
In any doubt ask the community to set up a production server for small cost for you (ask to support@ndda.fr).
Data pre-request:
- identify a nationName you want your town belongs to, this means that your tyown will follow the law of this nation (example: ants) - see nations list
- a townName that does not already exist (example:) towns list
- sudoerUser that will be create with root access right on your machine.
- a dns that redirect to your public IP server
- For dev on the same machine, add in /etc/hosts this line: 127.0.0.1 adminapx
- For dev on a different machine, add in /etc/hosts this line: {localIP} adminapx
- For prod, register a townname.nationname A IP adresss with your own domain name
see the free DNS Solution if you have not a domain [https://gitea.ndda.fr/apxtrib/apxtrib/wiki/UsefullfreeDNS]
to get your public IP https://www.whatismyip.com/
Physical pre-request:
For production:
- An ubuntu server > 20 (VPS or physical machine) with snap (sudo apt install snap if not yet installed) accessible from ssh root@IP adress. (you can purchase an industrial fanless plug & play on your network)
For dev:
- Any linux distro, but all tuto are based on ubuntu desktop set up with nginx visual studio, so just adapt to your tools.
This tuto will:
- use nginx to deal with ssl certificat (https) if chained (mean in production)
- use nginx as reverse proxy based on dns abd url to the apXtrib routes
- use nginx to serve static file based on dns and file name
- use pm2 to manage apxtrib.js, see pm2 doc
- serve adminapx interface onto http://adminapx webapp graphical interface to manage your setup and more
At the end
You will have a town server. Graphical interface will accessible as a public service on https://yourdns or local http://adminapx
To set up a machine
Replace phil with your sudoerUser
As root:
Create a safe user (with sudo access) in this example phil
sudo apt update
sudo apt upgrade
useradd -s /bin/bash -m -d /home/phil -c "phil" phil
passwd phil
sudo usermod -aG sudo phil
sudo visudo
# add the next line in the file
phil ALL=(ALL) NOPASSWD: ALL
# exit and save
su phil
sudo apt install git vim libcap2-bin p7zip-full p7zip-rar curl nginx
# Install last nvm** (check website to get latest v0.xx from https://github.com/nvm-sh/nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
# close and re-open terminal under phil
nvm --version
# if nvm not found then cc paste 3 last line : export NVM_DIR= ....
# and recheck nvm --version
# Install node/npm/yarn in general follow the directiv they gave online to update properly the config
nvm install node
node --version #to check
npm install --global yarn
yarn --version
install nginx and apixpress
FYI: dev will work without ssl, in production server nginx will manage ssl as a reverse proxy by using certbot let'sEncrypt certs.
sudo apt install nginx
#usefull command, you do not need it all back stuff will be under apxtrib.js control.
sudo systemctl (start|stop|reload|restart|status) nginx
#just check all is fine
sudo systemctl status nginx
#Make sudoUser the master of nginx conf, yarn setup will finish the apxtrib conf
sudo chown -R phil:phil /etc/nginx
git config --global credential.helper store
mkdir ~/workspace
cd workspace
git clone https://gitea.ndda.fr/apxtrib/apxtrib.git
cd apxtrib
yarn install
yarn setup // open in your browser http://adminapx to finish the setup
In dev we use the same machine to host and to dev so check you have in /etc/hosts this line
127.0.0.1 adminapx
In production check your public dns are well redirect to public IP's of the server. Open any terminal and check this command answer properly with your public IP
ping dns
Then check your firewall or router that a NAT exist and redirect the traffic on port 80 and 443 to your local IP server. To identify local IP of your server open a terminal in your server
ip a
Will show you the IP of your machine. Then depending of tou internet provider open your firewall.
**if you run for the 1st time then you need to set properly ~/workspace/apxtrib/nationchains/www/adminapx/townconf.json **
{
"nationId": "ants", // an existing nation
"townId": "wall", // a new town name
"IP":"213.32.65.213", // your public IP adresse where the trafic come from or 127.0.0.1 for dev
"tribeId":"ndda", // The first tribe of this town to manage the city of tribes
"dns": ["wallants.ndda.fr"],// The dns to access that have to be redirect to the server for dev add this line to your /etc/hosts: 127.0.0.1 myapxtrib
"mayorId":"philc", // An alias pagan that can exist or will be created as mayor (check that you own the private key
"passphrase":"", // Can be empty or not (if not each time something try to use your private key, it will request you a passphrase.
let other setup, except if you understand what you are doing
}
$ yarn setup
# Customize nginx conf by creating symlink ( @TODO: implemente it in the setup.js) replace /media/phil/HD1To by the relevant path where apixpress is
$ mv /etc/nginx/nginx.conf /etc/nginx/nginx.confsaved
$ cp /media/phil/HD1To/apixpress/data/nginx/nginx.conf /etc/nginx/nginx.conf
#change include /media/phil/HD1To/apixpress/data/nginx/conf.d by your location
# in dev check all servername exist into /etc/hosts as 127.0.0.1 website.clientid
$ sudo systemctl restart nginx
For dev
$ yarn dev # to test or dev<br>
$ yarn unittest # to run unittesting
Open your browser in http://adminapx then you are in your unchain town's interface as dev
Install the documentation wiki to update it directly in your editor, dopn't forget to push it if you have access right
cd ~/workspace
git clone https://gitea.ndda.fr/apxtrib/apxtrib.wiki.git
For production
As for dev, check your http://dsn answer correctly in your browser
install certbot of let's encrypt for https within nginx conf
replace townName.nationName.mooo.com by your data
# To get a ssl certificat in PRODUCTION with your sudoer user
sudo snap install core
sudo snap refresh core
sudo apt remove certbot
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
# manual command this is done by the setup sudo certbot --nginx -d townName.nationName.mooo.com
# The last command line is for information this will be run from you admin interface.
$ yarn startpm2
Check https://dns answer correctly.
That's it for the command line!
Usefull command
To list all the nginx conf that run under nginx, type in apxtrib folder
find . -name nginx_*.conf
yarn pm2 info apixpress
yarn logpm2 = yarn pm2 logs apixpress --lines 400
yarn pm2 monit apixpress
yarn startpm2 = yarn pm2 start apixpress.js --log-date-format 'DD-MM HH:mm:ss.SSS'
yarn stoppm2 = yarn pm2 stop apixpress.js
#Process to autostart (usefull if the server crash this will restart pm2 process)
# check apixpress is well started if not start it
yarn pm2 list
yarn pm2 startup (if they are nothing saved it will provide a command line to run then run it)
sudo env PATH=$PATH:/home/phil/.nvm/versions/node/v17.3.0/bin /home/phil/workspace/apixpress/node_modules/pm2/bin/pm2 startup systemd -u phil --hp /home/phil
# To stop autostart
yarn pm2 unstartup ; in case of error follow the command line provide like)
sudo env PATH=$PATH:/home/phil/.nvm/versions/node/v17.3.0/bin /home/phil/workspace/apixpress/node_modules/pm2/bin/pm2 unstartup systemd -u phil --hp /home/phil
in case of upgrade node version this can change
Backup & Loadbalancing
To back up your data, this can be valorized for your professionnal tribe. You can Shared your apxtrib space in 2 towns that you own (if they are not located at the same place)
Loadbalance
@TODO a tuto to setup this load balancing betwwen 2 towns
rsync IPA TownA tribe1 <-> IPB TownB tribe2 use the same dns and set a ssl for tribe1 & tribe2. Access both in ssh to rsync it
Set your registar with 2 IP adress or use a loadbalancer (stream with nginx) If TownA fail down => TownB will take it
Backup
@TODO Backup a tribes space in a roll process on external HD
each day / each 1st montth / each year until 3 years sh script in a crontab
Add an email sender account
If you have your own smtp system, you can add in data/apixpress/clientconf.json
Carrefull this email will be used to send messages with the Email, not to send massiv campain. Those email are not cipher from point to point (this means that the smtp provider can read those emails).
They are many ways to setup email account if you don't know how please ask community to set up for you.
Simply add this in ./nationchains/tribes/conf.json
smtpgoogle:{
From:{Email:,Name:},
service:"gmail",
auth:{ user:'gmail email', pass: 'user password'}
}
smtpmailjet:{
From:{Email,Name},
apikeypub:"",apikeypriv:""
}
Those accounts will be use if they do not exist in tribes/tribeId/conf.json or has reach maximum of sending.
Update repo apiXpress on npm
This is only for apiXpress maintener, but you can follow also this for your fork app. To publish on the npm repo you need to have a npm account with access right.
- check version
- Push the code in private repo gitlab.ndda.fr
- yarn login (check or provide your login and project) + yarn publish type new version
Version rules x.y.z z++ for bug correction no regression y++ for new function into a modele or new route with no regression x++ for possible regression
0.0.z Setup version of the project
#########This part have to be cleaned up and simplify
Quick command to run as user (not root):
$ cd apiXpress
$ NODE_ENV=prod pm2 start index.js
$ NODE_ENV=prodlight pm2 start light.js
To clean any pm2 process pm2 delete app
To save pm2 context pm2 save it save any process in /home/phil/.pm2/dump.pm2
In case of server crash simply pm2 resurrect to restart lattest saved service
To automatise starting process on reboot when pm2 process are currently running
pm2 unstartup
pm2 startup
to update a new version
To update a running prod with new git version:
- connect in SSH into the VM
- cd to folder
- Exec cmd for apiamaildigit.js :
$ git pull origin master
$ pm2 restart apiXpress --log-date-format 'DD-MM HH:mm:ss.SSS'
- Check log to identify any issues
$ pm2 logs apiXpress
SSL with let'sencrypt
SETUP to use as a SAAS serveur
Configuration with your domaine name: apixpress @ IP adresse of your box (need to have a fixed IP or noIp configuration) Redirect external port 80 or 443 port to the local IP adresse and port of your apixpress running
Webapp to manage apiXPress is available in: https://apixpress.yourdomain/public/app api is available on https://apixpress.yourdomain/
You can use this apixpress only as a package. If you want to dev your own platform and dev new features for apixpress, please create your own project (see next)
SETUP to use as external project
To install your fork just do the same than SAAS but with your own git projet set in SETUP4dev
index.js is the main point of the module where all exportable functions are:
const apixpress = {
checkHeaders: require('./middlewares/checkHeaders'),
isAuhtenticated: require('.middlewares/isAuthenticated'),
Referentials: require('./models/Referentials'),
referentials: require('./routes/referentials'),
Users: require('./models/Users'),
users: require('./routes/users')
}
module.exports = apixpress
route or middelwares are define with a lowercase as 1st letter
model are define with a uppercase as 1st letter.
This can be installed into any project with " yarn add apixpress "
To upgrade version in a project you can change in package.json {dependencies:{apixpres:"^0.0.1"}} then
###############################
yarn install