From dd853fe13b14941781495219897d9c1149ac76ec Mon Sep 17 00:00:00 2001 From: munja Date: Fri, 11 Feb 2022 12:05:05 +0100 Subject: [PATCH] chore(docs): adding contributing --- .github/CONTRIBUTING.md | 115 +++++++++++++++++++++++++++++ README.md | 155 ++++++++++------------------------------ 2 files changed, 153 insertions(+), 117 deletions(-) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..b901d08 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,115 @@ +# CONTRIBUTING + +Contributions are very welcome! Feel free to raise an issue or start a discussion, for help in getting started. + + +## Configuration + +Configuration is made in the `configuration` section of `package.json`: + +- Provide path to SAS9 executable. + + +### Using dockers: + +There is `.env.example` file present at root of the project. [for Production] + +There is `.env.example` file present at `./api` of the project. [for Development] + +There is `.env.example` file present at `./web` of the project. [for Development] + +Remember to provide enviornment variables. + +#### Development + +Command to run docker for development: + +``` +docker-compose up -d +``` + +It uses default docker compose file i.e. `docker-compose.yml` present at root. +It will build following images if running first time: + +- `sasjs_server_api` - image for sasjs api server app based on _ExpressJS_ +- `sasjs_server_web` - image for sasjs web component app based on _ReactJS_ +- `mongodb` - image for mongo database +- `mongo-seed-users` - will be populating user data specified in _./mongo-seed/users/user.json_ +- `mongo-seed-clients` - will be populating client data specified in _./mongo-seed/clients/client.json_ + + +#### Production + +Command to run docker for production: + +``` +docker-compose -f docker-compose.prod.yml up -d +``` + +It uses specified docker compose file i.e. `docker-compose.prod.yml` present at root. +It will build following images if running first time: + +- `sasjs_server_prod` - image for sasjs server app containing api and web component's build served at route `/` +- `mongodb` - image for mongo database +- `mongo-seed-users` - will be populating user data specified in _./mongo-seed/users/user.json_ +- `mongo-seed-clients` - will be populating client data specified in _./mongo-seed/clients/client.json_ + +### Using node: + +#### Development (running api and web seperately): + +##### API + +Navigate to `./api` +There is `.env.example` file present at `./api` directory. Remember to provide enviornment variables else default values will be used mentioned in `.env.example` files +Command to install and run api server. + +``` +npm install +npm start +``` + +##### Web + +Navigate to `./web` +There is `.env.example` file present at `./web` directory. Remember to provide enviornment variables else default values will be used mentioned in `.env.example` files +Command to install and run api server. + +``` +npm install +npm start +``` + +#### Development (running only api server and have web build served): + +##### API server also serving Web build files + +There is `.env.example` file present at `./api` directory. Remember to provide enviornment variables else default values will be used mentioned in `.env.example` files +Command to install and run api server. + +``` +cd ./web && npm i && npm build && cd ../ +cd ./api && npm i && npm start +``` + +#### Production + +##### API & WEB + +``` +npm run server +``` + +This will install/build `web` and install `api`, then start prod server. + + +## Executables + +Command to generate executables + +``` +cd ./web && npm i && npm build && cd ../ +cd ./api && npm i && npm run exe +``` + +This will install/build web app and install/create executables of sasjs server at root `./executables` diff --git a/README.md b/README.md index bd00f1d..25c8e6c 100644 --- a/README.md +++ b/README.md @@ -8,125 +8,56 @@ SASjs Server provides a NodeJS wrapper for calling the SAS binary executable. It One major benefit of using SASjs Server (alongside other components of the SASjs framework such as the [CLI](https://cli.sasjs.io), [Adapter](https://adapter.sasjs.io) and [Core](https://core.sasjs.io) library) is that the projects you create can be very easily ported to SAS 9 (Stored Process server) or Viya (Job Execution server). -## Installation +SASjs Server is available in two modes - Desktop (without authentication) and Server (with authentiation, and a database) +## Desktop Version -First, download the relevant package from the [releases](https://github.com/sasjs/server/releases) page - either manually, or with commandline, eg as follow: +### Manual Installation +Download the relevant package from the [releases](https://github.com/sasjs/server/releases) page -```bash -curl -L https://github.com/sasjs/server/releases/latest/download/linux.zip > linux.zip -unzip linux.zip -./api-linux -``` - -Second, trigger by double clicking (windows) or executing from commandline. +Next, trigger by double clicking (windows) or executing from commandline. You are presented with two prompts: * Location of your `sas.exe` / `sas.sh` executable * Path to a filesystem location for Stored Programs and temporary files -## Configuration -Configuration is made in the `configuration` section of `package.json`: +## Programmatic Installation -- Provide path to SAS9 executable. - -### Using dockers: - -There is `.env.example` file present at root of the project. [for Production] - -There is `.env.example` file present at `./api` of the project. [for Development] - -There is `.env.example` file present at `./web` of the project. [for Development] - -Remember to provide enviornment variables. - -#### Development - -Command to run docker for development: - -``` -docker-compose up -d -``` - -It uses default docker compose file i.e. `docker-compose.yml` present at root. -It will build following images if running first time: - -- `sasjs_server_api` - image for sasjs api server app based on _ExpressJS_ -- `sasjs_server_web` - image for sasjs web component app based on _ReactJS_ -- `mongodb` - image for mongo database -- `mongo-seed-users` - will be populating user data specified in _./mongo-seed/users/user.json_ -- `mongo-seed-clients` - will be populating client data specified in _./mongo-seed/clients/client.json_ - -#### Production - -Command to run docker for production: - -``` -docker-compose -f docker-compose.prod.yml up -d -``` - -It uses specified docker compose file i.e. `docker-compose.prod.yml` present at root. -It will build following images if running first time: - -- `sasjs_server_prod` - image for sasjs server app containing api and web component's build served at route `/` -- `mongodb` - image for mongo database -- `mongo-seed-users` - will be populating user data specified in _./mongo-seed/users/user.json_ -- `mongo-seed-clients` - will be populating client data specified in _./mongo-seed/clients/client.json_ - -### Using node: - -#### Development (running api and web seperately): - -##### API - -Navigate to `./api` -There is `.env.example` file present at `./api` directory. Remember to provide enviornment variables else default values will be used mentioned in `.env.example` files -Command to install and run api server. - -``` -npm install -npm start -``` - -##### Web - -Navigate to `./web` -There is `.env.example` file present at `./web` directory. Remember to provide enviornment variables else default values will be used mentioned in `.env.example` files -Command to install and run api server. - -``` -npm install -npm start -``` - -#### Development (running only api server and have web build served): - -##### API server also serving Web build files - -There is `.env.example` file present at `./api` directory. Remember to provide enviornment variables else default values will be used mentioned in `.env.example` files -Command to install and run api server. - -``` -cd ./web && npm i && npm build && cd ../ -cd ./api && npm i && npm start -``` - -#### Production - -##### API & WEB - -``` -npm run server -``` - -This will install/build `web` and install `api`, then start prod server. - -Normally the server process will stop when your terminal dies. To keep it going you can use the npm package [forever](https://www.npmjs.com/package/forever) as follows: +Fetch the relevant package from github using `curl`, eg as follows (for linux): ```bash -npm i -g forever -forever start -c "npm run server:start" ./ +curl -L https://github.com/sasjs/server/releases/latest/download/linux.zip > linux.zip +unzip linux.zip +``` + +The app can then be launched with `./api-linux` and prompts followed. + +When launching the app, it will make use of specific environment variables. These can be set in the following places: + +- Configured globally in /etc/environment file +- Export in terminal or shell script (`export VAR=VALUE`) +- Prepend in command +- Enter in the `.env` file alongside the executable + +Example variables: + +``` +PORT=5004 +SAS_PATH=/path/to/sas/executable.exe +DRIVE_PATH=./tmp +``` + +Setting these prompts variables will avoid the need for prompts. + +Normally the server process will stop when your terminal dies. To keep it going you can use the npm package [forever](https://www.npmjs.com/package/forever) (`npm i -g forever`) as follows: + +```bash +export SAS_PATH=/opt/sas9/SASHome/SASFoundation/9.4/sasexe/sas +export PORT=5001 +export DRIVE_PATH=./tmp + +forever start -c "./api-linux" ./ ``` To get the log files: @@ -142,13 +73,3 @@ To stop: forever stop ``` -## Executables - -Command to generate executables - -``` -cd ./web && npm i && npm build && cd ../ -cd ./api && npm i && npm run exe -``` - -This will install/build web app and install/create executables of sasjs server at root `./executables`