From 1f29b9ada22a66d362fa00817ebe8e843e7c345a Mon Sep 17 00:00:00 2001
From: Olivier Maury <Olivier.Maury@inrae.fr>
Date: Thu, 25 Jan 2024 09:42:46 +0100
Subject: [PATCH] =?UTF-8?q?D=C3=A9couper=20la=20documentation=20et=20ajout?=
=?UTF-8?q?er=20des=20pr=C3=A9cisions.=20refs=20#45?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
src/site/markdown/deployment.md | 54 ++++++++++
src/site/markdown/development.md | 86 ++++++++++++++++
src/site/markdown/index.md | 166 ------------------------------
src/site/markdown/installation.md | 66 ++++++++++++
src/site/site.xml | 6 +-
5 files changed, 210 insertions(+), 168 deletions(-)
create mode 100644 src/site/markdown/deployment.md
create mode 100644 src/site/markdown/development.md
create mode 100644 src/site/markdown/installation.md
diff --git a/src/site/markdown/deployment.md b/src/site/markdown/deployment.md
new file mode 100644
index 0000000..2d651bf
--- /dev/null
+++ b/src/site/markdown/deployment.md
@@ -0,0 +1,54 @@
+# Deployment on Tomcat
+
+## Requirements
+
+Tomcat 10.x is needed.
+
+To package sources, you must have:
+
+- Maven >= 3.8.0
+- JDK 17
+
+## Update database
+
+Just before deployment, make sure database migration are applied:
+
+```
+export PGOPTIONS="--search_path=agrometinfo"
+psql -h agrometinfo-prod -U agrometinfo -d agrometinfo -f sql/migration.sql
+```
+
+## Deployment
+
+Use the script `bin/deploy.sh` to deploy on Tomcat.
+This script uses Maven to package and deploy.
+
+with `~/.m2/settings.xml` with something like:
+
+```xml
+<servers>
+ <server>
+ <id>agrometinfo-preprod</id>
+ <configuration>
+ <cargo.remote.uri>http://agrometinfo-preprod:8080/manager/text</cargo.remote.uri>
+ <cargo.remote.username>tomcat-user</cargo.remote.username>
+ <cargo.remote.password>tomcat-password</cargo.remote.password>
+ </configuration>
+ </server>
+<servers>
+```
+
+You can run directly Maven to deploy the WAR on Tomcat. Eg. with server `agrometinfo-preprod`:
+
+```
+cd www-server
+mvn cargo:redeploy -Premote -Dcargo.server.settings=agrometinfo-preprod
+```
+
+
+If you want to deploy on <http://localhost:8080/agrometinfo> (server *localhost* and context *agrometinfo*):
+
+```
+mvn package
+mvn cargo:deploy -Premote -Dcargo.server.settings=localhost -Dcargo.server.context=agrometinfo
+```
diff --git a/src/site/markdown/development.md b/src/site/markdown/development.md
new file mode 100644
index 0000000..f9fc082
--- /dev/null
+++ b/src/site/markdown/development.md
@@ -0,0 +1,86 @@
+# Development
+
+## Update database
+
+Make sure your database has all migration applied.
+(not needed on a fresh installation).
+
+```
+export PGOPTIONS="--search_path=agrometinfo"
+psql -h localhost -U agrometinfo -d agrometinfo -f sql/migration.sql
+```
+
+## Requirements
+
+To package sources, you must have:
+
+- Maven >= 3.8.0
+- JDK 17
+
+## In Eclipse
+
+- Make sure `target/generated-sources/annotations` is in a folder for *www-shared* in Properties > Java Build Path > Sources.
+ This directory is created at compile time. Run `mvn compile` for example or use the Maven menu in Eclipse.
+- Create a new server with Tomcat 10.1 and JDK 17.
+- Configure `context.xml` for the embedded Tomcat.
+
+```xml
+ <Parameter name="agrometinfo.app.email" value="agrometinfoXXXX@inrae.fr" />
+ <Parameter name="agrometinfo.app.url" value="http://localhost:8080/www-server/" />
+ <Parameter name="agrometinfo.environment" value="dev" /> <!-- dev / preprod / prod -->
+ <Parameter name="agrometinfo.log.email" value="agrometinfoXXXX@inrae.fr" />
+ <Parameter name="agrometinfo.smtp.host" value="smtp.inrae.fr" />
+ <Parameter name="agrometinfo.smtp.port" value="587" />
+ <Parameter name="agrometinfo.smtp.user" value="agrometinfoXXXX" />
+ <Parameter name="agrometinfo.smtp.password" value="XXXX" />
+ <Parameter name="sava.key" value="XXXX" />
+ <Parameter name="sava.pass" value="XXXX" />
+ <Resource
+ name="jdbc/agrometinfo"
+ auth="Container"
+ driverClassName="org.postgresql.Driver"
+ initialSize="2"
+ maxTotal="10"
+ maxIdle="5"
+ maxWaitMillis="1000"
+ minEvictableIdleTimeMillis="60000"
+ minIdle="2"
+ removeAbandonedOnBorrow="true"
+ removeAbandonedOnMaintenance="true"
+ removeAbandonedTimeout="60"
+ testOnBorrow="true"
+ timeBetweenEvictionRunsMillis="30000"
+ type="javax.sql.DataSource"
+ url="jdbc:postgresql://127.0.0.1:5432/agrometinfo?ApplicationName=AgroMetInfo"
+ username="agrometinfo"
+ password="agrometinfo"
+ validationQuery="select 1" />
+```
+
+If CodeServer fails to launch in Eclipse, use the script
+
+```
+bin/start_codeserver.sh /path/to/eclipse-workspace/.metadata/.plugins/org.eclipse.wst.server.core/tmp*/wtpwebapps/agrometinfo-www-server/
+```
+
+Then browse <http://localhost:8080/www-server/>.
+
+You can edit Java files, CodeServer will recompile on page reloading (`F5` key).
+
+## Outside an IDE
+
+To launch the environment outside an IDE, follow the steps below:
+
+```sh
+mvn package
+bin/start_embeddedtomcat.sh
+# in another terminal
+bin/start_codeserver.sh
+```
+
+Then browse <http://localhost:8080/www-server/>.
+
+You can edit Java files, CodeServer will recompile on page reloading (`F5` key).
+To reflect on Tomcat, run `mvn package -DskipTests`.
+
+To run static analyses: `mvn checkstyle:checkstyle pmd:pmd pmd:cpd`.
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index f44576c..f7b7ec3 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -1,173 +1,7 @@
# Introduction to AgroMetInfo web site
-## Description
-
`agrometinfo-www` is the component of the AgroMetInfo the web site to display maps.
The static web site is developed at <https://forgemia.inra.fr/agroclim/agrometinfo/documentation>.
See [*MADR* decision log](adr/index.html).
-
-## Installation
-
-### Install database
-
-1. Create role with a password (here `agrometinfo`):
- ```
- sudo -u postgres psql -c "CREATE USER agrometinfo PASSWORD 'agrometinfo'"
- ```
-2. Create the database
- ```
- sudo -u postgres createdb agrometinfo --encoding=UTF8 --lc-collate=fr_FR.UTF-8 --lc-ctype=fr_FR.UTF-8 --owner=agrometinfo
- ```
-3. Adjust `pg_hba.conf` if needed
-4. Add the password to `~/.pgpass` if wanted
- ```
- localhost:5432:agrometinfo:agrometinfo:agrometinfo
- ```
-4. Create the schema:
- ```
- psql -h localhost -U agrometinfo -d agrometinfo -c 'CREATE SCHEMA "agrometinfo"'
- export PGOPTIONS="--search_path=agrometinfo"
- psql -h localhost -U agrometinfo -d agrometinfo -1 -f sql/schema.types.postgresql.sql
- psql -h localhost -U agrometinfo -d agrometinfo -1 -f sql/schema.tables.sql
- ```
-5. Add initialization data:
- ```
- export PGOPTIONS="--search_path=agrometinfo"
- cd sql/
- psql -h localhost -U agrometinfo -d agrometinfo -1 -f init_data.postgresql.sql
- ```
-6. Grant permissions to SEASON
- ```
- GRANT USAGE ON SCHEMA agrometinfo TO season;
- GRANT SELECT ON TABLE indicator TO season;
- GRANT ALL ON TABLE dailyvalue TO season;
- GRANT SELECT ON TABLE period TO season;
- GRANT SELECT ON TABLE normalvalue TO season;
- GRANT SELECT ON SEQUENCE dailyvalue_id_seq TO season;
- GRANT ALL ON SEQUENCE dailyvalue_id_seq TO season;
- ```
-
-### Package
-
-To package sources, you must have:
-
-- Maven >= 3.8.0
-- JDK 17
-
-### Configure Tomcat
-
-Define JNDI for the database and other parameters in `context.xml` of Tomcat.
-See example in `www-server/src/main/tomcat10xconf/context.xml`.
-
-Define credentials to deploy, change `conf/tomcat-users.xml` with
-
-```xml
-<role rolename="tomcat-user"/>
-<role rolename="manager-gui"/>
-<role rolename="manager-script"/>
-<user username="tomcat-password" password="tomcat" roles="tomcat,manager-gui,manager-script"/>
-```
-
-### Deployment
-
-Use Maven to deploy on Tomcat. Eg. with server `agrometinfo-preprod`:
-
-```mvn cargo:deploy -Premote -Dcargo.server.settings=agrometinfo-preprod```
-
-with `~/.m2/settings.xml` with something like:
-
-```xml
-<servers>
- <server>
- <id>agrometinfo-preprod</id>
- <configuration>
- <cargo.remote.uri>http://agrometinfo-preprod:8080/manager/text</cargo.remote.uri>
- <cargo.remote.username>tomcat-user</cargo.remote.username>
- <cargo.remote.password>tomcat-password</cargo.remote.password>
- </configuration>
- </server>
-<servers>
-```
-
-## Development
-
-### In Eclipse
-
-- Make sure `target/generated-sources/annotations` is in a folder for *www-shared* in Properties > Java Build Path > Sources.
-- Create a new server with Tomcat 10.1 and JDK 17.
-- Configure `context.xml` for the embedded Tomcat.
-
-```xml
- <Parameter name="agrometinfo.app.email" value="agrometinfoXXXX@inrae.fr" />
- <Parameter name="agrometinfo.app.url" value="http://localhost:8080/www-server/" />
- <Parameter name="agrometinfo.environment" value="dev" /> <!-- dev / preprod / prod -->
- <Parameter name="agrometinfo.log.email" value="agrometinfoXXXX@inrae.fr" />
- <Parameter name="agrometinfo.smtp.host" value="smtp.inrae.fr" />
- <Parameter name="agrometinfo.smtp.port" value="587" />
- <Parameter name="agrometinfo.smtp.user" value="agrometinfoXXXX" />
- <Parameter name="agrometinfo.smtp.password" value="XXXX" />
- <Parameter name="sava.key" value="XXXX" />
- <Parameter name="sava.pass" value="XXXX" />
- <Resource
- name="jdbc/agrometinfo"
- auth="Container"
- driverClassName="org.postgresql.Driver"
- initialSize="2"
- maxTotal="10"
- maxIdle="5"
- maxWaitMillis="1000"
- minEvictableIdleTimeMillis="60000"
- minIdle="2"
- removeAbandonedOnBorrow="true"
- removeAbandonedOnMaintenance="true"
- removeAbandonedTimeout="60"
- testOnBorrow="true"
- timeBetweenEvictionRunsMillis="30000"
- type="javax.sql.DataSource"
- url="jdbc:postgresql://127.0.0.1:5432/agrometinfo?ApplicationName=AgroMetInfo"
- username="agrometinfo"
- password="agrometinfo"
- validationQuery="select 1" />
-```
-
-If CodeServer fails to launch, use the script
-
-```
-bin/start_codeserver.sh /path/to/eclipse-workspace/.metadata/.plugins/org.eclipse.wst.server.core/tmp*/wtpwebapps/agrometinfo-www-server/
-```
-
-### Outside an IDE
-
-To launch the environment outside an IDE, follow the steps below:
-
-```sh
-mvn package
-bin/start_embeddedtomcat.sh
-# in another terminal
-bin/start_codeserver.sh
-```
-
-Then browse <http://localhost:8080/www-server/>.
-
-You can edit Java files, CodeServer will recompile on page reloading (`F5` key).
-To reflect on Tomcat, run `mvn package -DskipTests`.
-
-To run static analyses: `mvn checkstyle:checkstyle pmd:pmd pmd:cpd`.
-
-## Deployment
-
-To deploy on <http://localhost:8080/agrometinfo-domino>:
-
-```
-mvn package
-mvn cargo:deploy -Premote -Dcargo.server.settings=localhost -Dcargo.server.context=agrometinfo-domino
-```
-
-### Update database
-
-```
-export PGOPTIONS="--search_path=agrometinfo"
-psql -h localhost -U agrometinfo -d agrometinfo -f sql/migration.sql
-```
diff --git a/src/site/markdown/installation.md b/src/site/markdown/installation.md
new file mode 100644
index 0000000..8cf50a6
--- /dev/null
+++ b/src/site/markdown/installation.md
@@ -0,0 +1,66 @@
+# Installation
+
+## Install SEASON
+
+Only if you need to use real data, SEASON is needed, as well as [SEASON Handler](https://forgemia.inra.fr/agroclim/agrometinfo/season-handler).
+
+Otherwise, some example data are provided in initialization data for AgroMetInfo.
+
+## Install database
+
+1. Create role with a password (here `agrometinfo`):
+ ```
+ sudo -u postgres psql -c "CREATE USER agrometinfo PASSWORD 'agrometinfo'"
+ ```
+2. Create the database
+ ```
+ sudo -u postgres createdb agrometinfo --encoding=UTF8 --lc-collate=fr_FR.UTF-8 --lc-ctype=fr_FR.UTF-8 --owner=agrometinfo
+ ```
+3. Adjust `pg_hba.conf` if needed
+4. Add the password to `~/.pgpass` if wanted
+ ```
+ localhost:5432:agrometinfo:agrometinfo:agrometinfo
+ ```
+4. Create the schema:
+ ```
+ psql -h localhost -U agrometinfo -d agrometinfo -c 'CREATE SCHEMA "agrometinfo"'
+ export PGOPTIONS="--search_path=agrometinfo"
+ psql -h localhost -U agrometinfo -d agrometinfo -1 -f sql/schema.types.postgresql.sql
+ psql -h localhost -U agrometinfo -d agrometinfo -1 -f sql/schema.tables.sql
+ ```
+5. Add initialization data:
+ ```
+ export PGOPTIONS="--search_path=agrometinfo"
+ cd sql/
+ psql -h localhost -U agrometinfo -d agrometinfo -1 -f init_data.postgresql.sql
+ ```
+6. Grant permissions to SEASON
+ ```
+ GRANT USAGE ON SCHEMA agrometinfo TO season;
+ GRANT SELECT ON TABLE indicator TO season;
+ GRANT ALL ON TABLE dailyvalue TO season;
+ GRANT SELECT ON TABLE period TO season;
+ GRANT SELECT ON TABLE normalvalue TO season;
+ GRANT SELECT ON SEQUENCE dailyvalue_id_seq TO season;
+ GRANT ALL ON SEQUENCE dailyvalue_id_seq TO season;
+ ```
+
+## Install Tomcat
+
+Tomcat 10.x is needed.
+
+You can use the Bash script `update_tomcat.sh` from <https://agroclim.pages.mia.inra.fr/common/devops/> to install a version.
+
+## Configure Tomcat
+
+Define JNDI for the database and other parameters in `context.xml` of Tomcat.
+See example in `www-server/src/main/tomcat10xconf/context.xml`.
+
+Define credentials to deploy, change `conf/tomcat-users.xml` with
+
+```xml
+<role rolename="tomcat-user"/>
+<role rolename="manager-gui"/>
+<role rolename="manager-script"/>
+<user username="tomcat-password" password="tomcat" roles="tomcat,manager-gui,manager-script"/>
+```
diff --git a/src/site/site.xml b/src/site/site.xml
index 006fd42..9a24083 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -15,10 +15,9 @@
<sourceLineNumbersEnabled>true</sourceLineNumbersEnabled>
</fluidoSkin>
</custom>
- <edit>${project.scm.url}</edit>
<bannerLeft>
- <name>Documentation sur ${project.name}</name>
+ <name>${project.name} Documentation</name>
</bannerLeft>
<publishDate position="bottom" />
@@ -37,6 +36,9 @@
<menu name="${project.name}" >
<item name="Introduction" href="index.html" />
+ <item name="Installation" href="installation.html" />
+ <item name="Development" href="development.html" />
+ <item name="Deployment" href="deployment.html" />
<item name="Decision records" href="adr/index.html" />
</menu>
--
GitLab