From d898a090faa030ede1532c0883bfd3ed4693b25a Mon Sep 17 00:00:00 2001 From: "Steven R. Loomis" Date: Wed, 29 Nov 2023 11:32:15 -0600 Subject: [PATCH] CLDR-14316 doc: document SurveyTool setup --- tools/cldr-apps/README.md | 72 ++++++++++++++++++++++++++++++++------- 1 file changed, 60 insertions(+), 12 deletions(-) diff --git a/tools/cldr-apps/README.md b/tools/cldr-apps/README.md index cd9b951de85..d96442011b9 100644 --- a/tools/cldr-apps/README.md +++ b/tools/cldr-apps/README.md @@ -6,17 +6,49 @@ The `cldr-apps` subproject builds `cldr-apps.war` which contains the Survey Tool packaged for deployment. The Survey Tool is used to collect and confirm translations for CLDR. + +## DB setup + +- Setup MySQL or MariaDB +- Create a database (schema), named `cldrdb` with codepage `latin1` and collation `latin1_bin` (Yes, ironic) + +```sql +CREATE SCHEMA `cldrdb` DEFAULT CHARACTER SET latin1 COLLATE latin1_bin ; +``` + +- Create a user `surveytool` + +```sql +create user 'surveytool'@'localhost' IDENTIFIED BY 'your_strong_password'; +``` + +- Grant the user `surveytool` “all” privileges + +```sql +GRANT ALL PRIVILEGES ON cldrdb.* TO 'surveytool'@'localhost'; +``` + ## Building and Running the Survey Tool Please use the parent [CLDR/tools/pom.xml](../pom.xml) with maven to build and run. - Copy `src/main/liberty/config/server.env.sample` to `src/main/liberty/config/server.env` -- Edit that `server.env` file to contain the MySQL credentials for the ST database -- Use `mvn --file=tools/pom.xml -pl cldr-apps liberty:dev` to run a development -web server, listening on port 9080 +- Edit that `server.env` file to contain the MySQL credentials for the ST database (from above). + +```ini +MYSQL_USER=surveytool +MYSQL_PASSWORD=your_strong_password +MYSQL_DB=cldrdb +``` + +- Use `mvn --file=tools/pom.xml -DskipTests=true -pl cldr-apps liberty:dev` to run a development +web server, listening on port 9080. Hit control-C to cancel the server. + - Navigate to http://localhost:9080/cldr-apps to view the app -See for further information +- See [Configuration](#configuration) below. You will need to restart the server after edit. + +See for out of date information about the Survey Tool. ## Using Logging @@ -65,7 +97,7 @@ docker run --rm -p 8025:8025 -p 1025:1025 mailhog/mailhog Then browse to http://localhost:8025 to watch mail flow in. -Then, setup SurveyTool with these `cldr.properties`: +Then, setup SurveyTool with these `cldr.properties` (see [Configuration](#configuration)) ```properties CLDR_SENDMAIL=true @@ -89,18 +121,34 @@ mail.smtp.port=1025 #CLDR_MAIL_BATCHSIZE=0 ## How long to wait between each mail in the batch. CLDR_MAIL_DELAY_BATCH_ITEM=0 +``` + +### Configuration + +SurveyTool is configured with a `cldr.properties` file which is created on first startup. It must be edited before +SurveyTool can start working, to remove the `CLDR_MAINTENANCE=true` line. + +You will also likely want to change the `CLDR_DIR` property in that file to point to your CLDR root, otherwise a new CLDR root will be checked out. + +Search for this file in your Java workspace after launching - it may be in a random place. See [Advanced Configuration](#advanced-configuration) below for how to move this directory. On one system the cldr directory was in `tools/cldr-apps/target/liberty/wlp/usr/servers/cldr/cldr`. On the production and staging servers, the location is `/srv/st/config` + +#### Advanced Configuration + +- There is the file `tools/cldr-apps/src/main/liberty/config/jvm.options` which supplies the default memory settings for SurveyTool, this file is checked in. + +- The 'CLDR Home' directory as mentioned above is normally in a random location determined by the server. To fix its location, create a file `tools/cldr-apps/src/main/liberty/config/bootstrap.properties` with the following: + +```ini +org.unicode.cldr.util.CLDRConfigImpl.cldrHome=/Users/srl295/src/cldr-st/config ``` -### Licenses +You will also want to make sure this directory exists and is writeable. You can move the existing `cldr.properties` and other files to that directory. -- Usage of CLDR data and software is governed by the [Unicode Terms of Use](https://www.unicode.org/copyright.html) -a copy of which is included as [LICENSE](../../LICENSE). +### Licenses -For more details, see the main [README.md](../../README.md). +See the main [README.md](../../README.md). ### Copyright -Copyright © 1991-2021 Unicode, Inc. -All rights reserved. -[Terms of use](https://www.unicode.org/copyright.html) +Copyright © 2004-2023 Unicode, Inc. Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. in the United States and other countries.