Ajouter 'Setup'
commit
e242c82882
330
Setup.md
Normal file
330
Setup.md
Normal file
@ -0,0 +1,330 @@
|
|||||||
|
# How to Setup a town
|
||||||
|
|
||||||
|
** ******************** **
|
||||||
|
This tuto will:
|
||||||
|
|
||||||
|
* use nginx to proxy any url/app to the apiXpress routes
|
||||||
|
* use nginx to serve static file for clientId in https
|
||||||
|
* create env to start apixpress.js with PM2 production env (see [pm2 doc](https://pm2.keymetrics.io/docs/usage/pm2-doc-single-page/)
|
||||||
|
* conf linux to backup your client's data
|
||||||
|
* create your clientId space with an admin user on your apiXPress instance
|
||||||
|
* serve the apiXpress webapp graphical interface to manage your env (create new ClientId space, manage your server's ressource,...
|
||||||
|
|
||||||
|
**At the end** you will have a town instance link to the nationchains or a town dev to create plugin or add feature to apiXtribe.
|
||||||
|
|
||||||
|
**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 apiXtribe 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).
|
||||||
|
|
||||||
|
**Pre-request**:
|
||||||
|
An ubuntu server version > 20 (VPS, physical machine,....) accessible from ssh root@IP address.
|
||||||
|
This setup process was tested on LXC ubuntu/focal.
|
||||||
|
|
||||||
|
snapd (snap --version) is already installed by default, need to install it if not ($ sudo apt install snap).
|
||||||
|
|
||||||
|
For your physical machine (only way to decentralize the control) see https://ubuntu.com/tutorials/install-ubuntu-server#1-overview
|
||||||
|
You can use any other linux distro but you need to write your own setup.js .If you do please send us your setup (support@apixpress.org) and we'll share to the community. Also, share other way to set up (other static web engine, apache, haproxy, ...). Less standardization means more security. You'll find the process install in models/Setup.js. It collects necessary data then run a bunch of command. We kept command line install for software we use in case their install process evolve before we can update this tuto. In case of any issue please contact any admin of an apiXtribe instance.
|
||||||
|
|
||||||
|
## To add a town to a nation
|
||||||
|
|
||||||
|
---
|
||||||
|
**Parameter to anticipate**:
|
||||||
|
- nationName: you want to join (check it's rules) ex: ants nation. ..
|
||||||
|
- townName: as futur mayor choose a uniq town name, check https://apixtribe.crabdance.com to check existing town as a dev type 'devtown'.
|
||||||
|
- sudoerUser: linux user you want to use (will be sudoer) ex:phil or name of your town
|
||||||
|
if for prod:
|
||||||
|
- townIP: as futur mayor your public IP where your instance
|
||||||
|
-
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
A domain name (like ndda.fr in this tuto) that you can buy anywhere (bookmyname, ovh, ....) that allow you to create a subdomain apixpress.ndda.fr to a A or AAAA record to the IP server you control.
|
||||||
|
|
||||||
|
As root:<br>
|
||||||
|
Create a safe user (with sudo access) in this example phil
|
||||||
|
```
|
||||||
|
sudo apt-get update
|
||||||
|
sudo apt-get upgrade
|
||||||
|
useradd -s /bin/bash -m -d /home/phil -c "phil" phil
|
||||||
|
passwd phil
|
||||||
|
usermod -aG sudo phil
|
||||||
|
sudo visudo
|
||||||
|
\# add the next line in the file
|
||||||
|
phil ALL=(ALL) NOPASSWD: ALL
|
||||||
|
\# exit and save
|
||||||
|
sudo apt-get install git vim libcap2-bin p7zip-full p7zip-rar
|
||||||
|
\# Install last nvm** (check website to get latest v0.xx)
|
||||||
|
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
|
||||||
|
nvm --version
|
||||||
|
\# if nvm not found then cc paste 3 last line : export NVM_DIR= ....
|
||||||
|
\# and recheck nvm --version
|
||||||
|
\# Install node/npm/yarn**
|
||||||
|
nvm install node
|
||||||
|
node --version #to check
|
||||||
|
npm install --global yarn
|
||||||
|
yarn --version
|
||||||
|
\# Allow a simple user to listen on port 80
|
||||||
|
sudo setcap cap_net_bind_service=+ep /usr/local/bin/node
|
||||||
|
```
|
||||||
|
**install nginx**
|
||||||
|
```
|
||||||
|
sudo apt-get install nginx
|
||||||
|
#usefull command, you do not need it all back stuff will be under apixpress.js control.
|
||||||
|
sudo systemctl (start|stop|reload|restart|status) nginx
|
||||||
|
```
|
||||||
|
A specific data/nginx/nginx.conf and data/nginx/conf.d/*.conf file will be generate after the 1st install apixpress to make it works as http.
|
||||||
|
|
||||||
|
**PRODUCTION PURPOSE**
|
||||||
|
**install certbot of let's encrypt for https**
|
||||||
|
as root
|
||||||
|
```
|
||||||
|
snap install core
|
||||||
|
snap refresh core
|
||||||
|
apt-get remove certbot
|
||||||
|
snap install --classic certbot
|
||||||
|
ln -s /snap/bin/certbot /usr/bin/certbot
|
||||||
|
# manual command this is done by the setup sudo certbot --nginx -d apixpress.ndda.fr
|
||||||
|
```
|
||||||
|
|
||||||
|
The last command line can be done for each new client @todo integrate it in the process of adding a website for a client
|
||||||
|
|
||||||
|
dns/app/ => apixpress.js route (header set related to dns)
|
||||||
|
dns/spacedev/ => nginx serve static file /data/domain/clientid/spacedev/website/dist/
|
||||||
|
dns/cdn/ => nginx serve from /data/domain/clientid/www/cdn/
|
||||||
|
dns/www/ => nginx serve from /data/domain/clientid/www/app/website/
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
**install apixpress**
|
||||||
|
|
||||||
|
Install without ssl, dev will work without ssl, in production server nginx will manage ssl as a reverse proxy by using certbot let'sEncrypt certs.
|
||||||
|
|
||||||
|
```
|
||||||
|
git config --global credential.helper store
|
||||||
|
mkdir ~/workspace
|
||||||
|
cd workspace
|
||||||
|
git clone http://gitlab.ndda.fr/philc/apixpress.git
|
||||||
|
cd apixpress
|
||||||
|
yarn install
|
||||||
|
```
|
||||||
|
if you run for the 1st time then you need to set properly /setup/configsetup.json
|
||||||
|
```
|
||||||
|
{
|
||||||
|
"linuxuser": "phil", (user with sudo access right)
|
||||||
|
"mode": "dev", (dev will affect only http and /etc/hosts prod need to have a dns pointing on the IP address port 80)
|
||||||
|
"domain": "local.fr",
|
||||||
|
"subdomain": "dev",
|
||||||
|
"consoleloglevel": "verbose" | "quiet" use first "quiet" if issue then set to verbose
|
||||||
|
"porthttp": 3018, port where backoffice answer
|
||||||
|
"language": ["fr", "en"],
|
||||||
|
"jwtsecret": "longsentenceusedtoencryptionChangethisforproduction",
|
||||||
|
"clientIdadmin": "test", name of your organisation (a-z) have to be unique
|
||||||
|
"login": "testadmin", login of the user admin of clientId
|
||||||
|
"genericpsw": "@12ABab@", generique password for all new user by default to access for 1st time.
|
||||||
|
}
|
||||||
|
|
||||||
|
$ 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
|
||||||
|
$ yarn dev # to test or dev<br>
|
||||||
|
if it is a production server then<br>
|
||||||
|
$ yarn startpm2
|
||||||
|
```
|
||||||
|
|
||||||
|
Usefull command:
|
||||||
|
```
|
||||||
|
\# in DEV
|
||||||
|
yarn dev = "node apixpress.js" all is log in the terminal
|
||||||
|
|
||||||
|
\# in PRODUCTION
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
To check apixpress is running properly type into web browser https://dns/app<br>
|
||||||
|
To access apiXpress Manager graphical user interface type: https://apixpress.domain <br>
|
||||||
|
|
||||||
|
## To add a town for dev purpose
|
||||||
|
|
||||||
|
As dev you'll squeeze many steps, you can use this dev install to:
|
||||||
|
* understand how this works localy without to be connected to the blockchain (nationchains)
|
||||||
|
* add local tribe to dev plugin or website to allow your clients (tribe's druid) to show and validate with them what they request you to do.
|
||||||
|
* dev new features that you want to add to the apiXtribe community and earn Xcoin if the tech comitee valide your code
|
||||||
|
* Audit the code to highlight security fail and gain some Xcoin in our bounty challenge for any fail discover
|
||||||
|
* You can also try to pentest other towns to improve security
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Backup & maintenance
|
||||||
|
|
||||||
|
To back up your client data, this can be valorized for your professionnal clientId. You can also exchange between 2 apixpress server the physical backup.
|
||||||
|
|
||||||
|
Add external hard drive (at least in size 12 x the apiXpress/data space) and a {backupFolder} like **/mnt/hdexterne2/backup**
|
||||||
|
Add cloud scp access like phil@192.168.1.6:/mnt/hdexterne/fullbackup user phil has to have the same GUID number to work without asking password.
|
||||||
|
|
||||||
|
Then login as phil (ssh phil@IP)
|
||||||
|
```
|
||||||
|
// Add interaction with a root shell
|
||||||
|
$root crontab -e
|
||||||
|
// each 10mn update IP and a freedns domain to access externaly to the server nd.mooo.com (in case no fix IP)
|
||||||
|
3,13,23,33,43,53 * * * * sleep 31 ; wget -O - http://freedns.afraid.org/dynamic/update.php?KEY
|
||||||
|
// each day at 3:00 run a backup data process
|
||||||
|
0 3 * * * /root/cron/databckup.sh > /home/phil/workspace/apixpress/data/domain/apixpress/logs/backup.log 2>&1
|
||||||
|
```
|
||||||
|
|
||||||
|
copy & paste to vim /root/cron/databackup.sh
|
||||||
|
```
|
||||||
|
#!/bin/bash
|
||||||
|
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin
|
||||||
|
// Backup script
|
||||||
|
// apiXPress/data Tar encrypted with /root/.pass
|
||||||
|
// roll backup into external hd that can be send to the cloud
|
||||||
|
// Tar et encrypte databckup dans databckup4export incrementale tourne tous les jours (7 fichiers de 1 à 7, 1 = lundi)
|
||||||
|
echo "tar file";
|
||||||
|
tar czf - /home/phil/workspace/apiXpress/data | openssl enc -e -aes-256-cbc -out /mnt/hdexterne2/backup/databckup$(date +%u) -pass file:/root/.pass
|
||||||
|
// copy bckup encrypté sur 192.168.1.6:2206
|
||||||
|
scp -P 2206 /mnt/hdexterne2/backup/databckup$(date +%u) phil@192.168.1.6:/mnt/hdexterne/fullbckup
|
||||||
|
// test if 1st day of the month to copy monthbackup
|
||||||
|
if [ `date +%d` == "01" ]
|
||||||
|
then
|
||||||
|
cp /mnt/hdexterne2/backup/databckup$(date +%u) /mnt/hdexterne2/backup/databckupmonth$(date +%B);
|
||||||
|
scp -P 2206 /mnt/hdexterne2/backup/databckupmonth$(date +%B) phil@192.168.1.6:/mnt/hdexterne/fullbckup;
|
||||||
|
fi
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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 crypté fro point to point (this means that the smtp provider can read those emails).<br>
|
||||||
|
They are many ways to setup email account if you don't know how please ask community to set up for you.
|
||||||
|
|
||||||
|
```
|
||||||
|
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 clientId/clientconf.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**<br>
|
||||||
|
To save pm2 context **pm2 save** it save any process in /home/phil/.pm2/dump.pm2 <br>
|
||||||
|
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<br>
|
||||||
|
pm2 unstartup<br>
|
||||||
|
pm2 startup <br>
|
||||||
|
|
||||||
|
**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
|
||||||
|
```shell
|
||||||
|
$ 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<br>
|
||||||
|
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 ```
|
||||||
Loading…
Reference in New Issue
Block a user