README.md
... ...
@@ -74,12 +74,113 @@ See [here](https://www.sapsailing.com/gwt/Home.html#/imprint/:) for a list of co
74 74
75 75
## Building and Running
76 76
77
-This assumes you have completed the onboarding (see again [here](https://wiki.sapsailing.com/wiki/howto/onboarding)) successfully. To build, then invoke
77
+Builds usually run on [GitHub Actions](https://github.com/SAP/sailing-analytics/actions/workflows/release.yml) upon every push. A few repository secrets ensure that the build process has the permissions it needs. Pushes to the ``main``, ``docker-24`` and ``releases/*`` branches also publish a [release](https://github.com/SAP/sailing-analytics/releases) after a successful build.
78
+
79
+There are two options for building, detailed below; for both, you need to fulfill a few prerequisites.
80
+
81
+### Prerequisites
82
+
83
+If you have forked the repository and would like to run your own build, you will need the following prerequisites:
84
+
85
+#### Google Maps API Key
86
+
87
+Create or log on to your Google account and go to the [Google Cloud Console](https://console.cloud.google.com/apis/) and create an API key at least for the Maps JavaScript API. To later run the full product, while you're here, you can also create an API key for the YouTube Data API v3.
88
+
89
+#### AWS S3 Bucket for Upload Tests
90
+
91
+The build runs integration tests using the AWS API, requiring an access key with permission to upload to a bucket called ``sapsailing-automatic-upload-test``. Create that bucket in your AWS S3 environment. You can create an IAM user with CLI access and a permission policy that restricts write permissions to just that test bucket. You have to create the bucked in AWS region ``eu-west-1``. A permission policy for that user can look like this:
92
+
93
+```
94
+{
95
+ "Version": "2012-10-17",
96
+ "Statement": [
97
+ {
98
+ "Sid": "Stmt1422015883000",
99
+ "Effect": "Allow",
100
+ "Action": [
101
+ "s3:AbortMultipartUpload",
102
+ "s3:DeleteObject",
103
+ "s3:DeleteObjectVersion",
104
+ "s3:GetBucketAcl",
105
+ "s3:GetBucketCORS",
106
+ "s3:GetBucketLocation",
107
+ "s3:GetBucketLogging",
108
+ "s3:GetBucketNotification",
109
+ "s3:GetBucketPolicy",
110
+ "s3:GetBucketTagging",
111
+ "s3:GetBucketVersioning",
112
+ "s3:GetBucketWebsite",
113
+ "s3:GetLifecycleConfiguration",
114
+ "s3:GetObject",
115
+ "s3:GetObjectAcl",
116
+ "s3:GetObjectTorrent",
117
+ "s3:GetObjectVersion",
118
+ "s3:GetObjectVersionAcl",
119
+ "s3:GetObjectVersionTorrent",
120
+ "s3:ListAllMyBuckets",
121
+ "s3:ListBucket",
122
+ "s3:ListBucketMultipartUploads",
123
+ "s3:ListBucketVersions",
124
+ "s3:ListMultipartUploadParts",
125
+ "s3:PutBucketLogging",
126
+ "s3:PutBucketNotification",
127
+ "s3:PutBucketPolicy",
128
+ "s3:PutBucketTagging",
129
+ "s3:PutBucketVersioning",
130
+ "s3:PutBucketWebsite",
131
+ "s3:PutLifecycleConfiguration",
132
+ "s3:PutObject",
133
+ "s3:PutObjectAcl",
134
+ "s3:PutObjectVersionAcl",
135
+ "s3:RestoreObject"
136
+ ],
137
+ "Resource": [
138
+ "arn:aws:s3:::sapsailing-automatic-upload-test/*",
139
+ "arn:aws:s3:::sapsailing-automatic-upload-test"
140
+ ]
141
+ }
142
+ ]
143
+}
144
+```
145
+
146
+Create an access key for that user and note key ID and secret.
147
+
148
+#### Account(s) for geonames.org
149
+
150
+The build runs integration tests against [geonames.org](https://geonames.org). Use their login/sign-up form to create your user account and note its username.
151
+
152
+### Get the GitHub Actions build to work in your forked repository
153
+
154
+Assign the IDs and secrets from the prerequisites to repository secrets in your forked repository as follows:
155
+
156
+```
157
+AWS_S3_TEST_S3ACCESSID: {your-S3-test-bucket-upload-token-ID}
158
+AWS_S3_TEST_S3ACCESSKEY: {key-for-your-S3-token}
159
+GEONAMES_ORG_USERNAMES: {comma-separated-list-of-geonames.org-usernames}
160
+GOOGLE_MAPS_AUTHENTICATION_PARAMS: key={your-Google-Maps-API-key}
161
+```
162
+
163
+Then, manually trigger the ``release`` workflow with default options. You find the "Run workflow" drop-down in your forked repository under ``https://github.com/{your-github-user}/[your-repository-name}/actions/workflows/release.yml``.
164
+
165
+Release builds will trigger the ``create-docker-image`` workflow which will produce a Docker image of your release and publish it as a "ghcr" package in your repository. Note that package names are computed from the repository name by converting the latter to all lowercase characters.
166
+
167
+### Run a build locally
168
+
169
+This assumes you have completed the onboarding (see again [here](https://wiki.sapsailing.com/wiki/howto/onboarding)) successfully, including the Maven-specific parts such as having Maven installed (>= 3.9.x) and having a valid ``toolchains.xml`` file in your ~/.m2 folder. Furthermore, set and export the following environment variables:
170
+
171
+```
172
+export AWS_S3_TEST_S3ACCESSID={your-S3-test-bucket-upload-token-ID}
173
+export AWS_S3_TEST_S3ACCESSKEY={key-for-your-S3-token}
174
+export GEONAMES_ORG_USERNAMES={comma-separated-list-of-geonames.org-usernames}
175
+export GOOGLE_MAPS_AUTHENTICATION_PARAMS=key={your-Google-Maps-API-key}
176
+```
177
+
178
+To build, then invoke
78 179
79 180
```
80 181
configuration/buildAndUpdateProduct.sh build
81 182
```
82
-This will build the Android companion apps first, then the web application. If the build was successful you can install the product locally by invoking
183
+This will build the Android companion apps first, then the web application. If you lack a proper Android SDK set-up, consider using the ``-a`` option to skip building the Android apps. If the build was successful you can install the product locally by invoking
83 184
84 185
```
85 186
configuration/buildAndUpdateProduct.sh install [ -s <server-name> ]