From 476344d34d9d541926a965b94fc7f5f93a31a088 Mon Sep 17 00:00:00 2001 From: Raruto Date: Mon, 1 Aug 2022 10:52:26 +0200 Subject: [PATCH] update `README.md` (docker development) related to: https://github.com/g3w-suite/g3w-client/pull/29 --- README.md | 238 +++++++++++++++++++++++++++++++++++++++++---------- package.json | 10 ++- 2 files changed, 202 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index ecb23dc37..08096a64e 100755 --- a/README.md +++ b/README.md @@ -1,77 +1,227 @@ -# G3W-SUITE +# G3W-CLIENT v3.5-dev -G3W-CLIENT client module for G3W-SUITE. +[![License](https://img.shields.io/badge/license-MPL%202-blue.svg?style=flat)](LICENSE) +G3W-SUITE scripts and configuration files needed to set up a suitable local development enviroment for the [g3w-client](https://g3w-suite.readthedocs.io/en/latest/g3wsuite_client.html) cartographic viewer. -The following instructions are for a Ubuntu 18.04 LTS. +![g3w-client](https://g3w-suite.readthedocs.io/en/latest/_images/g3wclient_interface.png) -## Installation of node.js +--- + +## Project setup + +Download and install [Node.js and NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) and [Docker Compose](https://docs.docker.com/compose/install/) in your development enviroment. + +Clone and place the [g3w-suite-docker](https://github.com/g3w-suite/g3w-suite-docker), [g3w-admin](https://github.com/g3w-suite/g3w-admin) and [g3w-client](https://github.com/g3w-suite/g3w-client) repositories into three separated adjacent folders: + +```sh +cd /path/to/your/development/workspace + +git clone https://github.com/g3w-suite/g3w-suite-docker.git --single-branch --branch dev ./g3w-suite-docker +git clone https://github.com/g3w-suite/g3w-admin.git --single-branch --branch dev ./g3w-admin +git clone https://github.com/g3w-suite/g3w-client.git --single-branch --branch dev ./g3w-client +``` +Download all javascript and docker dependencies from within your [g3w-client](https://github.com/g3w-suite/g3w-client) local repository: + +```sh +cd ./g3w-client +``` +```sh +npm install # javascript dependencies (client) +``` +```sh +npm run docker pull # docker dependencies (admin) +``` + +Create these configuration files from the available templates: + +- `/g3w-client/config.js` ← [config.template.js](https://github.com/g3w-suite/g3w-client/config.template.js) +- `/g3w-client/src/config/dev/index.js` ← [index.template.js](https://github.com/g3w-suite/g3w-client/src/config/dev/index.template.js) +- `/g3w-client/src/config/keys/index.js` ← [index.template.js](https://github.com/g3w-suite/g3w-client/src/config/keys/index.template.js) +- `/g3w-suite-docker/.env` ← [.env.example](https://github.com/g3w-suite/g3w-suite-docker/.env.example) +- `/g3w-suite-docker/config/g3w-suite/settings_docker.py` ← [settings_docker.py](https://github.com/g3w-suite/g3w-suite-docker/config/g3w-suite/settings_docker.py) +- `/g3w-suite-docker/shared-volume/` ← add this folder if it doesn't exist + +And check that the following parameters are set as follows: + +```sh +# /g3w-suite-docker/.env + +WEBGIS_DOCKER_SHARED_VOLUME=./shared-volume # path to docker container shared volume +G3WSUITE_LOCAL_CODE_PATH=../g3w-admin # path to local g3w-admin folder +G3WSUITE_DEBUG=True # default: False +``` + +Now your folder structure should matches this one: -```bash -sudo apt-get install -y nodejs-legacy npm ``` +. +├── g3w-admin/ +│ +├── g3w-client/ +│ ├── node_modules/ +│ ├── src/ +│ │ └── config/ +│ │ ├── dev/ +│ │ │ └── index.js +│ │ └── keys/ +│ │ └── index.js +│ ├── package.json +│ ├── package-lock.json +│ └── config.js +│ +└── g3w-suite-docker/ + ├── config/ + │ └── g3w-suite/ + │ └── settings_docker.py + ├── shared-volume/ + ├── scripts/ + │ └── docker-entrypoint-dev.sh + ├── .env + ├── docker-compose-dev.yml + └── README_DEV.md + +``` + +For more info about this project dependencies see: -Note: You have to install Node version => v16.13.2 +- [package.json](https://github.com/g3w-suite/g3w-client/package.json) +- [docker-compose-dev.yml](https://github.com/g3w-suite/g3w-suite-docker/docker-compose-dev.yml) +--- -## Install G3W-CLIENT development dependencies +## How to develop -The following instruction will install all node modules mandatory to use development enviromental +You can start the built-in development servers by using the following: -```bash -npm install +```sh +npm run docker:up # g3w-admin ``` -## Local Server Configuration +```sh +npm run dev # g3w-client +``` + +If everything went fine, you can now visit you local development server URL to see changes, the following rules are applied: + +```sh +# EXAMPLE 1: +# project_group = "countries"; +# project_type = "qdjango"; +# project_id = "1" + +http://localhost:8000/en/map/countries/qdjango/1 # g3w-admin (production) +http://localhost:3000/?project=countries/qdjango/1 # g3w-client (development) +``` + +```sh +# EXAMPLE 2: +# project_group = "eleprofile"; +# project_type = "qdjango"; +# project_id = "2" + +http://localhost:8000/en/map/eleprofile/qdjango/2 # g3w-admin (production) +http://localhost:3000/?project=eleprofile/qdjango/2 # g3w-client (development) +``` + +--- + +### FAQ + +
-This is the front-end part of the G3W-SUITE. Before run it in develop mode YOU NEED TO INSTALL AND RUN the server part [**g3w-admin**](https://github.com/g3w-suite/g3w-admin) +1. How can I start or stop docker containers? -After server side installation you can customize local server configuration through "config.js" file +For those unfamiliar with docker development [docker-compose](https://docs.docker.com/compose/) is a tool for defining and running multi-container applications. +Below are described the most frequent commands, that are also available here in this repository as [npm scripts](https://docs.npmjs.com/cli/run-script/), you can find similar information by running `npm run` from the command line. -1) Create a new file named config.js form config.template.js and change local G3W-ADMIN path, server port, etc ..: - ```bash - ~/../g3w-client$ nano config.js - ``` -Go to ***g3w-client/src/config/dev*** folder and create a new ***index.js*** from index.template.js setting dev configuration +Define and run the services that make up the g3w-client (admin) development server: -Go to ***g3w-client/src/config/keys*** folder and create a new ***index.js*** from index.template.js setting your GOOGLE and BING KEYS +``` +docker + docker compose --env-file ../g3w-suite-docker/.env --file ../g3w-suite-docker/docker-compose-dev.yml --project-name g3w-suite-docker --project-directory ../g3w-suite-docker +``` + +Create and start containers (run default admin server at [localhost:8000](http://localhost:8000)): + +``` +docker:up + npm run docker up -- -d +``` + +Stop and remove containers, networks, images, and volumes: + +``` +docker:down + npm run docker down +``` + +Validate and view the Compose file (load and parse [docker-compose-dev.yml](https://github.com/g3w-suite/g3w-suite-docker/docker-compose-dev.yml) and [.env](https://github.com/g3w-suite/g3w-suite-docker/.env.example) variables): + +``` +docker:config + npm run docker config +``` + +View output from containers: + +``` +docker:logs + npm run docker logs +``` + +For more info: + +- [Overview of docker-compose CLI](https://docs.docker.com/compose/reference/) + +
+ +
+ +2. How can I inspect actual docker configuration? + +If you are having trouble with your current project configuration you can use the docker config command to inspect the actual values of the variables passed to your docker container: + +```sh +npm run docker config +``` + +If your container struggles to boot properly you can also use the docker logs command related to a specific container: + +```sh +npm run docker logs g3w-suite -- -f +npm run docker logs postgis -- -f +``` -```js{1,2} -export const GOOGLE_API_KEY = ''; -export const BING_API_KEY = ''; -export default { - GOOGLE_API_KEY, - BING_API_KEY -}``` +For more info: -## Development Task Command +- [Overview of g3w-suite dockerization](https://g3w-suite.readthedocs.io/en/latest/docker.html) +
-We use [**Gulp**](https://gulpjs.com/) for automating tasks in development +
+3. How can I translate this project? -The main gulp commands to use in develop enviroment are: +Depending on your current project version, you can edit one of the following files and then submit a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request): -1."Default Commad". It used to run local server. Run it from ~/../g3w-client$ +- `/g3w-client/src/locales/` (> v3.4) +- `/g3w-client/src/config/i18n/index.js` (<= v3.4) - ```bash - ~/../g3w-client$ npm run default - ``` -2."Admin Command". It used to build and copy the client files (.js, .css, etc..) and index.html template to g3w-admin client folders +
- ```bash - npm run admin - ``` +### Changelog -# Internationalization -It is possible to add internationalization translation adding/modified g3w-client/src/config/i18n/index.js +All notable changes to this project are documented in the [releases](https://github.com/g3w-suite/g3w-client/releases) page. -#Run web client -After add a group and at least one qgis project in admin you can run web client application following the below rules: +--- -Es ADMIN_URL: http://localhost:8000/en/map/group1-maps/qdjango/1/ where http://localhost:8000/en/map//// +**Compatibile with:** +[![g3w-admin version](https://img.shields.io/badge/g3w--admin-3.4-1EB300.svg?style=flat)](https://github.com/g3w-suite/g3w-admin) +[![g3w-suite-docker version](https://img.shields.io/badge/g3w--suite--docker-1.0-1EB300.svg?style=flat)](https://github.com/g3w-suite/g3w-suite-docker) -Es CLIENT_URL: http://localhost:3000/?project=group1-maps/qdjango/1 where http://localhost:3000/?project=// +--- +**License:** MPL-2 \ No newline at end of file diff --git a/package.json b/package.json index 2b018e286..c808845cf 100755 --- a/package.json +++ b/package.json @@ -8,8 +8,14 @@ "admin": "gulp g3w-admin --max-old-space-size=2048", "admin:client": "gulp g3w-admin:client_only --max-old-space-size=2048", "plugins": "gulp g3w-admin-plugins-select", - "default": "gulp default --max-old-space-size=2048", - "dev": "npm run default", + "default": "npm run dev", + "dev": "gulp default --max-old-space-size=2048", + "docker": "docker compose --env-file ../g3w-suite-docker/.env --file ../g3w-suite-docker/docker-compose-dev.yml --project-name g3w-suite-docker --project-directory ../g3w-suite-docker", + "docker:pull": "npm run docker pull", + "docker:up": "npm run docker up -- -d", + "docker:down": "npm run docker down", + "docker:config": "npm run docker config", + "docker:logs": "npm run docker logs", "test": "gulp test", "cy:open": "cypress open", "preversion": "npm run test",