Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md (docker development) #104

Merged
merged 1 commit into from
Aug 1, 2022
Merged

Update README.md (docker development) #104

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
238 changes: 194 additions & 44 deletions README.md
View file
Open in desktop
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
Open in desktop
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