Skip to content

Commit

Permalink
Merge pull request #104 from g3w-suite/readme
Browse files Browse the repository at this point in the history 
Update `README.md` (docker development)
  • Loading branch information
@volterra79
volterra79 authored Aug 1, 2022
2 parents 4c214ba + 476344d commit e88d541
Show file tree
Hide file tree
Showing 2 changed files with 202 additions and 46 deletions.
238 changes: 194 additions & 44 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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

<details>

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)
<summary>1. How can I start or stop docker containers?</summary>

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/)

</details>

<details>

<summary>2. How can I inspect actual docker configuration?</summary>

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 = '<INSERT HERE YOUR GOOGLE API KEY>';
export const BING_API_KEY = '<INSERT HERE YOUR 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)

</details>

We use [**Gulp**](https://gulpjs.com/) for automating tasks in development
<details>

<summary>3. How can I translate this project?</summary>

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
</details>

```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/<group_name_in_lower_case>/<project_type>/<id_project>/
**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=<group_name_in_lower_case>/<project_type>/<id_project>
---

**License:** MPL-2
10 changes: 8 additions & 2 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down

0 comments on commit e88d541

Please sign in to comment.