From 8093fca756423689c789872624082db3c1b15b68 Mon Sep 17 00:00:00 2001 From: philc Date: Fri, 24 Feb 2023 14:50:24 +0100 Subject: [PATCH] update wiki --- Devrules | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Setup.md | 67 ++++++++++++++++++++++++++-------------------------- 2 files changed, 105 insertions(+), 34 deletions(-) create mode 100644 Devrules diff --git a/Devrules b/Devrules new file mode 100644 index 0000000..77f950d --- /dev/null +++ b/Devrules @@ -0,0 +1,72 @@ +# Developeur + +This page is about to save time to a dev to quickly onboard to add a features or debug any issues. This is also a good start if you want just dev a plugin for a tribe. + +## Key point + +* this is a npm/yarn classical organization (package.json give you 1st info) +* Entry point ./apxtrib.js +* apXtrib is organize around an express.js api and respect the restFULL concept on an object. +* An object has: + - a unique objectName + - a metadata definition that describe each character to qualify an object + - a route named ./routes/objectName.js from the api /objectName/ parameters to request acting on items of this objectName + - a model named ./models/ObjectName.js that act on items +* Access control is done by 3 middlewares: + - checkHeaders.js that check ./tribes/townconf.json.exposedHeaders are presents + - isAuthenticated.js check the token (header.xauth ) for header.xpaganid is valid + - hasAccessrighton.js check accessright of pagan to act (CRUD) on an object into a tribe (xworkon) +* Multilanguage management + +### apXtrib Coding Convention + +Standard: Eslint 6 with a .eslintrc.js + +lib used for: +* file json manipulation: fs-extra.js +- templating szysteme: mustache.js +- encryption with simple hash : bcrypt that is more efficient than crypto-js that is use inside a browser or node for cypher and uncipher +- time management use luxon and no more moment +* cross domain management: cors.js +* to generate unique id use lib uuid.v4() +* stripe to allow payment in $,€,... any device + +In general try to not install other lib in your dev. An apXtrib town mayor have to globaly valid to add a new lib into apxtrib so if you do then you can only use your town to provide your service and cannot use other town to deal wwith. + + +### CORS and global + +global variable into node: +* ${__base} is the current dir where project are install in case you need absolute path. +* config is set from ./tribes/townconf.json where: + - system data are available to sync town and nation (linux user, url, nation and town name) + - express set up parameter appset allow to set any key:val parameter of express + - +* const app is an express instance that is set into apixtrib.js + + +### Object organization + + +### route template + +A route analyse (data structur and user accesright) a http request to act a model action + +### model template + +A model is a logical to apply onto an object. It is indepedant of the interface +export model to make it importable into route or any other app + + + + +### Object Nationschains + + +### Object Contracts + + +### Object Tribes + + + diff --git a/Setup.md b/Setup.md index 7446b85..fc6eb0f 100644 --- a/Setup.md +++ b/Setup.md @@ -8,13 +8,12 @@ In any doubt ask the community to set up a production server for small cost for **Data pre-request:** -* identify a **nationName** you want to belong to - see [nations list](https://apxtrib.crabdance.com/socialworld/objects/nations/searchindex/nationslist.json) -* a **townName** that does not exist [towns list](https://apxtrib.crabdance.com/socialworld/objects/nations/searchindex/townslist.json) -* **sudoerUser** with root access right on your machine -* a dns that redirect to your public IP server - - For dev: set /etc/hosts with 127.0.0.1 townName.nationName.localnation - - For prod: register a townname.nationname A IP adresss (see the free DNS Solution)[https://gitea.ndda.fr/apxtrib/apxtrib/wiki/UsefullfreeDNS] to get your public IP [https://www.whatismyip.com/](https://www.whatismyip.com) - +* identify a **nationName** you want to belong to (example: ants) - see [nations list](https://apxtrib.crabdance.com/socialworld/objects/nations/searchindex/nationslist.json) +* a **townName** that does not exist (example:) [towns list](https://apxtrib.crabdance.com/socialworld/objects/nations/searchindex/townslist.json) +* **sudoerUser** that will be create with root access right on your machine +* a **dns** that redirect to your public IP server + - For dev: we'll use keyword unchain set in /etc/hosts with 127.0.0.1 townName.nationName.unchain + - For prod: example: mooo.com, register a townname.nationname A IP adresss with your own domaine (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/](https://www.whatismyip.com) **Physical pre-request:** @@ -24,19 +23,17 @@ For production: 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) +* 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](https://pm2.keymetrics.io/docs/usage/pm2-doc-single-page/) -* create your tribe space call townname with an admin user -* serve the apxtrib webapp graphical interface to manage your env (create new ClientId space, manage your server's ressource,... ) [Link to ] +* create your tribes space with your tribe call townname with a Pagan's accessright of druid of your tribe and mayor of your town. +* serve the apxtrib webapp graphical interface to manage your env (create new ClientId space, manage your server's ressource,... ) **At the end** -* **For production:** you will have a town live instance link to the nationchains. Graphical interface will be on https://townName.nationName.mooo.com with your data -* **For dev:** a local town with no link to the nationchains, to create/test plugins/new feature, that you can also use as pre-prod availble in http://townname.nationName.localnation +* **For production:** you will have a town live instance link to the nationchains. Graphical interface will be on https://townName.nationName.dns with your data +* **For dev:** a local town with **no link to the nationchains**, to create/test plugins/new feature, that you can also use as pre-prod available in http://townname.nationName.unchain ## To set up a machine @@ -49,59 +46,61 @@ Create a safe user (with sudo access) in this example phil sudo apt upgrade useradd -s /bin/bash -m -d /home/phil -c "phil" phil passwd phil - usermod -aG sudo phil + sudo usermod -aG sudo phil sudo visudo # add the next line in the file phil ALL=(ALL) NOPASSWD: ALL # exit and save - sudo apt install git vim libcap2-bin p7zip-full p7zip-rar + su phil + sudo apt install git vim libcap2-bin p7zip-full p7zip-rar curl # 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 + # 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** + # 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 - # Allow a simple user to listen on port 80 + # OPTION if needed Allow a simple user to listen on port 80 on this machine sudo setcap cap_net_bind_service=+ep /usr/local/bin/node ``` **install nginx** ``` sudo apt install nginx -#usefull command, you do not need it all back stuff will be under apixpress.js control. +#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 ``` -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. + +FYI: A specific data/nginx/nginx.conf file will be generate after the 1st install apixpress to make it works as http. **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. +FYI: 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 https://gitea.ndda.fr/apxtrib/apxtrib.git - cd apixpress + cd apxtrib yarn install ``` -if you run for the 1st time then you need to set properly /setup/configsetup.json +**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. + "sudoerUser": "phil - your sudoer user that will run nginx and apxtrib", + "mode": "dev | prod - dev will affect only http and /etc/hosts prod need to have a dns pointing on the IP address port 80 ", + "nationName": "ants - an existing nation", + "townName": "devndda - a unique townName that is not in activity", + "dns":"apxtrib.dev | mooo.com ... - dns domain where townName.nationName.dns is set to send web traffic to IP:80|443 ", + "apiport": 3018 - let it except if this port is already use for other services on the machine, api will be route to this port + "language": ["fr", "en"], to set language in this town ("en" is default and minimum) + "jwtsecret": "longsentenceusedtoencryptionChangethisforproduction" } $ yarn setup