Mercurial > gemma

annotate README.md @ 4424:0bfecb6beda1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: improve phrasing in main README
author Bernhard Reiter <bernhard@intevation.de>
date Wed, 18 Sep 2019 15:44:52 +0200
parents ab08a74ad2f4
children 43c52a2d4f17
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1262
f370ce6eab65 add license info to README.md
Bernhard Reiter <bernhard@intevation.de>
parents: 1009
diff changeset
1 # Workingtitle "gemma"
f370ce6eab65 add license info to README.md
Bernhard Reiter <bernhard@intevation.de>
parents: 1009
diff changeset
2
4424
0bfecb6beda1 docs: improve phrasing in main README
Bernhard Reiter <bernhard@intevation.de>
parents: 4117
diff changeset
3 //"gemma" is a working title and is likely to be changed.//
1262
f370ce6eab65 add license info to README.md
Bernhard Reiter <bernhard@intevation.de>
parents: 1009
diff changeset
4
1263
00a38b354ab7 improve licening info in README.md
Bernhard Reiter <bernhard@intevation.de>
parents: 1262
diff changeset
5
266
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
6 # Quick Start
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
7
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
8 ## Build
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
9
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
10 - To build all components of gemma, simply type `make` on the top
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
11 level directory of the repro.
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
12
1009
76e9296d6191 added demo mode in READMEs
Markus Kottlaender <markus@intevation.de>
parents: 615
diff changeset
13 - To build all components of gemma, with client in demo mode, use `make demo`.
76e9296d6191 added demo mode in READMEs
Markus Kottlaender <markus@intevation.de>
parents: 615
diff changeset
14
266
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
15 - To only (re)build the back end you can use `make gemma`.
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
16
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
17 - To only build the SPA-Client you can use `make client`.
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
18
1009
76e9296d6191 added demo mode in READMEs
Markus Kottlaender <markus@intevation.de>
parents: 615
diff changeset
19 - To only build the SPA-Client in demo mode you can use `make clientdemo`.
76e9296d6191 added demo mode in READMEs
Markus Kottlaender <markus@intevation.de>
parents: 615
diff changeset
20
4424
0bfecb6beda1 docs: improve phrasing in main README
Bernhard Reiter <bernhard@intevation.de>
parents: 4117
diff changeset
21 For further details see [docs/DEVELOPMENT](docs/DEVELOPMENT.md).
291
9d6ba97a31d2 Moved development infos to separate file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 272
diff changeset
22
266
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
23
4117
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
24 ## Running Tests
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
25
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
26 - Running database tests:
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
27
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
28 * You will need a PostgreSQL cluster with PostGIS and pgTAP.
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
29 * To run the tests use the script `./schema/run_tests.sh`.
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
30 * `./schema/run_tests.sh --help` shows you available options.
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
31 Per default the script will create (and drop if it already exists)
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
32 a database named "gemma_test" and all necessary roles in the postgres
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
33 default cluster (listening on port 5432) and run the tests
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
34 in that database.
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
35 * The script must be run as a user with PostgreSQL super user rights.
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
36 By convention this is "postgres" on most systems.
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
37
ab08a74ad2f4 Document how to run database tests
Tom Gottfried <tom@intevation.de>
parents: 1390
diff changeset
38
266
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
39 ## Setup Database
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
40
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
41 - You will need a PostgreSQL cluster with PostGIS.
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
42
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
43 - To install the **gemma** schema and roles use the script
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
44 `./schema/install-db.sh`.
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
45
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
46 - `./schema/install-db.sh --help` shows you available options.
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
47 Per default the script will create a database named "gemma" and all
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
48 necessary roles in the postgres default cluster (listening on port
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
49 5432).
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
50
272
5ee0edc01a18 Small typo fix.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 266
diff changeset
51 - The script must be run as a user with PostgreSQL super user rights.
266
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
52 By convention this is the "postgres" on most systems.
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
53
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
54
610
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
55 ## Setup GeoServer
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
56
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
57 - Install and run GeoServer as described here:
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
58 http://docs.geoserver.org/stable/en/user/installation/
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
59
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
60 - Add tables you want to publish as OGC-Service Layers via GeoServer in
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
61 the database. For example publish the bottleneck areas:
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
62 ```
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
63 INSERT INTO sys_admin.published_services (name, as_wfs) VALUES
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
64 ('waterway.bottlenecks', true);
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
65 ```
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
66 In case your gemma is already running (see next section), restart it.
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
67 Published WFS services will be available at `/api/internal/wfs`. Currently,
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
68 the same layers will also be available as WMS services at
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
69 `/api/internal/wms`, regardless of the value of `as_wms` in
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
70 `sys_admin.published_services`.
f62ee9d5bff1 Document adding of layers to internal OGC services.
Tom Gottfried <tom@intevation.de>
parents: 481
diff changeset
71
266
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
72 ## Running gemma
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
73
330
fd04bccae6ca Create standard roles as part of the base schema.
Sascha Wilde <wilde@intevation.de>
parents: 291
diff changeset
74 - Best is to create a configuration file. Copy the example from
481
d68dfbe768e2 Merge example configuration and that used for docker backend
Tom Gottfried <tom@intevation.de>
parents: 479
diff changeset
75 `example_conf.toml` to get started:
330
fd04bccae6ca Create standard roles as part of the base schema.
Sascha Wilde <wilde@intevation.de>
parents: 291
diff changeset
76 ```
481
d68dfbe768e2 Merge example configuration and that used for docker backend
Tom Gottfried <tom@intevation.de>
parents: 479
diff changeset
77 cp example_conf.toml gemma.toml
330
fd04bccae6ca Create standard roles as part of the base schema.
Sascha Wilde <wilde@intevation.de>
parents: 291
diff changeset
78 ```
266
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
79
387
0f78b13f4a9a (minor) Fix typo in README.
Bernhard Reiter <bernhard@intevation.de>
parents: 330
diff changeset
80 - Edit `gemma.toml`, some parameters you probably want to change:
330
fd04bccae6ca Create standard roles as part of the base schema.
Sascha Wilde <wilde@intevation.de>
parents: 291
diff changeset
81
fd04bccae6ca Create standard roles as part of the base schema.
Sascha Wilde <wilde@intevation.de>
parents: 291
diff changeset
82 * `host` and `port` to make gemma listen on a public interface
481
d68dfbe768e2 Merge example configuration and that used for docker backend
Tom Gottfried <tom@intevation.de>
parents: 479
diff changeset
83 * `metamorph-db-password` to match the password for your database user
d68dfbe768e2 Merge example configuration and that used for docker backend
Tom Gottfried <tom@intevation.de>
parents: 479
diff changeset
84 * `geoserver-url`, `geoserver-user` and `geoserver-password` to match
d68dfbe768e2 Merge example configuration and that used for docker backend
Tom Gottfried <tom@intevation.de>
parents: 479
diff changeset
85 your instance of GeoServer
266
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
86
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
87 - `./cmd/gemma/gemma -h` gives you an overview of more available
a2f7049daf7f Added some quickstart information to README.md
Sascha Wilde <wilde@intevation.de>
parents: 206
diff changeset
88 options.
330
fd04bccae6ca Create standard roles as part of the base schema.
Sascha Wilde <wilde@intevation.de>
parents: 291
diff changeset
89
fd04bccae6ca Create standard roles as part of the base schema.
Sascha Wilde <wilde@intevation.de>
parents: 291
diff changeset
90 - Then start gemma:
fd04bccae6ca Create standard roles as part of the base schema.
Sascha Wilde <wilde@intevation.de>
parents: 291
diff changeset
91 ```
479
fce16726f51d Add missing command
Tom Gottfried <tom@intevation.de>
parents: 434
diff changeset
92 ./cmd/gemma/gemma
330
fd04bccae6ca Create standard roles as part of the base schema.
Sascha Wilde <wilde@intevation.de>
parents: 291
diff changeset
93 ```
615
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
94
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
95 ## Proxying OGC services through gemma
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
96
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
97 - Add services you want to publish via gemma (e.g. for same-origin policy
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
98 compliance reasons) in the database. For example:
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
99 ```
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
100 INSERT INTO sys_admin.external_services (local_name, remote_url, is_wfs)
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
101 VALUES ('d4d', 'https://service.d4d-portal.info/wamos/wfs', true);
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
102 ```
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
103 In case your gemma is already running (see previous section), restart it.
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
104 The services will be available at `/api/external/${local_name}`, thus in
4ffdb922db44 Document adding of external OGC services.
Tom Gottfried <tom@intevation.de>
parents: 610
diff changeset
105 the example given above: `/api/external/d4d`.
1390
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
106
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
107 # License
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
108
4424
0bfecb6beda1 docs: improve phrasing in main README
Bernhard Reiter <bernhard@intevation.de>
parents: 4117
diff changeset
109 //gemma// source code itself is licensed as Free Software
0bfecb6beda1 docs: improve phrasing in main README
Bernhard Reiter <bernhard@intevation.de>
parents: 4117
diff changeset
110 under GNU Affero GPL v>=3. See the specific source files
1390
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
111 for details, the license itself can be found in the directory `LICENSES`.
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
112
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
113 To build a complete product, a number of other Free Software components
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
114 are used, which have their own licenses.
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
115
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
116 To get an overview about the components which are partly included
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
117 in the resulting production ready-product for the `client/`
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
118 use `yarn licenses`, e.g. like
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
119
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
120 ```sh
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
121 yarn licenses list | grep '^├─ '
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
122 ```
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
123
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
124 Additionally inspect `3rdpartylibs.sh` for Go components used
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
125 for the middleware and their licenses.
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
126
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
127 # Credits
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
128
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
129 Exclusive usage rights
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
130 (we are in Europe, so it is not Common-law's "copyright"):
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
131 via donau – Österreichische Wasserstraßen-Gesellschaft mbH, Austria
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
132
69e0b75c0cc8 Moved license and credits sections to end of the readme file.
Sascha L. Teichmann <sascha.teichmann@intevation.de>
parents: 1271
diff changeset
133 Software-Engineering: Intevation GmbH, Germany