more corrections to deployment configuration

Author: Pascal-Delange

.env.example

@@ -8,12 +8,6 @@
 # REQUIRED SETTINGS
 #
 
-# If equal to "development", applies configurations on the backend and frontend containers that
-# are not suitable for production, related to CORS, secure cookies and https.
-# Any other value works for a production environment, and will be used by sentry to mark the environment
-# an error occurred in.
-ENV=production
-
 # Ports respectively used by the backend API and the frontends containers
 # Maps to the "PORT" environment variable in the backend and frontend containers
 # respectively.
@@ -29,9 +23,9 @@ HOST_APP_PORT=3000
 # Must include the scheme (e.g http://), and the port if non-standard.
 MARBLE_APP_URL="http://localhost:3000"
 
-# Set the value to the URL the Marble API can be reached at. Must include the scheme (e.g http://)
-# "MARBLE_API_URL_SERVER" must be reachable from the frontend host. With docker-compose, use the api container name as host name.
-MARBLE_API_URL_SERVER="http://api:8080"
+# Set the value to the URL the Marble API can be reached at, from the frontend host. Must include the scheme (e.g http://)
+# With docker-compose, use the api container name as host name.
+MARBLE_API_URL="http://api:8080"
 
 # RSA private key, in PEM format, used for for signing authentication tokens. MUST be changed for production.
 # We recommend using AUTHENTICATION_JWT_SIGNING_KEY_FILE to point to a private key on disk because multi-line
@@ -91,12 +85,19 @@ FIREBASE_API_KEY=
 
 # Generate a random string, for instance using `openssl rand -base64 128 | tr -d "\n"`
 SESSION_SECRET=changeme
-SESSION_MAX_AGE=43200
 
 #
 # OPTIONAL SETTINGS
 #
 
+# Used for minor logging and telemetry settings. In particular, it will be used by sentry to mark the environment
+# an error occurred in. Do not touch it in the general case and it should work fine.
+# *DO NOT* set it to "development" for production purposes, as this specifically enables some unsafe settings.
+# ENV=production
+
+# Configure the frontend cookie session max age, in seconds. Defaults to 43200
+# SESSION_MAX_AGE=43200
+
 # Set your license key here if you have one in order to access premium features.
 LICENSE_KEY=
 

docker-compose-dev.yaml

@@ -6,7 +6,6 @@ x-frontend-image-version: &frontend-image-version
   image: europe-west1-docker.pkg.dev/marble-infra/marble/marble-frontend:v0.53.0
 
 x-shared-environment: &shared-env
-  ENV: development
   MARBLE_APP_URL: http://localhost:${HOST_APP_PORT:-3000}
   DISABLE_SEGMENT: ${DISABLE_SEGMENT:-false}
 x-backend-environment: &backend-env

docker-compose.yaml

@@ -39,8 +39,6 @@ x-backend-environment: &backend-env
   CREATE_ORG_NAME: ${CREATE_ORG_NAME}
   CREATE_ORG_ADMIN_EMAIL: ${CREATE_ORG_ADMIN_EMAIL}
 
-  FIREBASE_API_KEY: ${FIREBASE_API_KEY}
-
   METABASE_SITE_URL: ${METABASE_SITE_URL}
   METABASE_JWT_SIGNING_KEY: ${METABASE_JWT_SIGNING_KEY}
   METABASE_GLOBAL_DASHBOARD_ID: ${METABASE_GLOBAL_DASHBOARD_ID}

installation/baremetal.md

@@ -70,20 +70,21 @@ Copy the [example configuration](https://github.com/checkmarble/marble-backend/b
 
 - Set the `PG_*` variables to point to your PostgresSQL instance.
 - Set the `GOOGLE_CLOUD_PROJECT` to the ID of your Firebase project.
-- The `GOOGLE_APPLICATION_CREDENTIALS` should contain the path to the JSON private key file downloaded from Firebase.
+- The `GOOGLE_APPLICATION_CREDENTIALS` should contain the path to the JSON private key file downloaded from Firebase/GCP.
+- Set `FIREBASE_API_KEY` with the information retrieved from your Firebase account.
 - Set `AUTHENTICATION_JWT_SIGNING_KEY_FILE` to point to the generated RSA private key at `/etc/marble/jwtsigningkey.pem`.
 - `*_BUCKET_URL`should point to buckets in your blob storage platform (S3, Azure Blob or GCS).
-If you are using Minio, use a URL such as `s3://<bucket>?awssdk=v1&endpoint=minio.domain.com&region=us-east-1&s3ForcePathStyle=true`. In this case, you may also add `disableSSL=true` if your MinIO instance is in cleartext.
-You might have to add provider-specific configuration, for example for authentication (for S3 and MinIO, for example, set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
-- Set the `CREATE_*` variables to specify your initial organization and admin user.
+  If you are using Minio, use a URL such as `s3://<bucket>?awssdk=v1&endpoint=minio.domain.com&region=us-east-1&s3ForcePathStyle=true`. In this case, you may also add `disableSSL=true` if your MinIO instance is in cleartext.
+  You might have to add provider-specific configuration, for example for authentication (for S3 and MinIO, for example, set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`).
+- Set the `CREATE_*` variables to specify your initial organization and admin user - this needs to be run only once and can be omitted after the first run.
 - Set your `LICENCE_KEY`.
-- Set `MARBLE_APP_URL` to the URL used to access the frontend.
+- Set `MARBLE_APP_URL` to the external HTTP base your users’ browsers can use to reach the frontend.
 
 ### Service configuration
 
 Marble’s backend is composed of five discrete services, three of which are scheduled tasks. Those can be configured with the following systemd units:
 
-#### API *(persistent service)*
+#### API _(persistent service)_
 
 ```bash
 # /etc/systemd/system/marble-api.service
@@ -103,7 +104,7 @@ ExecStart=/opt/marble/api/marble-backend -server
 WantedBy=multi-user.target
 ```
 
-#### Worker *(persistent service)*
+#### Worker _(persistent service)_
 
 ```bash
 # /etc/systemd/system/marble-worker.service
@@ -123,7 +124,7 @@ ExecStart=/opt/marble/api/marble-backend -worker
 WantedBy=multi-user.target
 ```
 
-#### Database migrator *(manual run only)*
+#### Database migrator _(manual run only)_
 
 ```bash
 # /etc/systemd/system/marble-migrate.service
@@ -170,16 +171,12 @@ $  curl http://127.0.0.1:8080/liveness
 Copy the [example configuration](https://github.com/checkmarble/marble-frontend/blob/main/packages/app-builder/.env.example) file into `/etc/marble/front.conf`and edit the relevant settings. Among others:
 
 - `NODE_ENV` must be set to `production`.
-- `ENV` should be set to `production`.
-Note that this will require setting up TLS certificates to access the frontend. If prototyping without TLS, set this to `development`.
 - Set a random, high-entropy `SESSION_SECRET`.
-- `MARBLE_API_URL_SERVER` should be the external HTTP base your users’ browsers can use to reach the API.
-- `MARBLE_APP_URL` should be set to the external HTTP base your users’ browsers can use to reach the frontend.
-- Set the different Firebase configuration settings with the information retrieved from your Firebase account.
+- `MARBLE_API_URL` should be the internal HTTP base your frontend service can use to reach the API.
 
 ### Service configuration
 
-Drop this `systemd`unit file in ``/etc/systemd/system/marble-front.service``:
+Drop this `systemd`unit file in `/etc/systemd/system/marble-front.service`:
 
 #### Frontend
 
@@ -201,7 +198,6 @@ ExecStart=/opt/marble/front/node_modules/@remix-run/serve/dist/cli.js ./build/se
 WantedBy=multi-user.target
 ```
 
-
 And start the frontend service by running:
 
 ```bash

installation/production_run.md

@@ -217,43 +217,25 @@ Reference the following files for detailed configuration:
 
 ### Common Issues
 
-1. **CORS Errors**
+1. **API URL Configuration**
 
-   - Ensure `MARBLE_APP_URL` environment variable is set correctly
-   - Must use `https://` protocol in production
-   - Example: `MARBLE_APP_URL=https://app.yourdomain.com`
-   - Common symptoms:
-     - API requests failing in browser
-     - Console errors about CORS policy
-     - Authentication issues
+- Frontend needs one API URL configured:
 
-2. **API URL Configuration**
-
-<<<<<<< HEAD
-
-- # Frontend needs one API URL configured:
-- Frontend needs one API URLs configured:
-
-  > > > > > > > 32b0710 (Edit production guide to match requirements for IAM.)
-
-       - `MARBLE_API_URL_SERVER`: URL for container-to-container requests
-         - Example: `http://api:8080` (Docker internal network)
-       - `MARBLE_API_URL_CLIENT`: URL for browser requests (public URL)
-         - Example: `https://api.yourdomain.com`
+  - `MARBLE_API_URL`: URL for container-to-container requests
+    - Example: `http://api:8080` (Docker internal network)
 
 - Incorrect configuration leads to:
-  - Failed API calls
-  - CORS errors
-  - Authentication failures
+  - Missing variable means the frontend container will not start
+  - Wrong value, or unreachable network, means the container will start but fail immediately as soon as you try to access the page
 
-3. **Network Connectivity**
+2. **Network Connectivity**
 
    - Confirm services can reach each other
    - Check firewall rules
    - Verify DNS resolution works
    - Test internal container networking
 
-4. **Invalid Google Cloud Service Account**
+3. **Invalid Google Cloud Service Account**
 
 Check Marble's startup logs for messages related to Google Cloud Platform's authentication, they may be able to point your to a potential misconfiguration:
 
@@ -273,13 +255,13 @@ Those lines indicate:
 
 You can verify that those value match your environment if you encounter any issue.
 
-5. **Firebase Configuration**
+4. **Firebase Configuration**
 
 - Service account:
 
   - Check that the detected Google Cloud project and service account match your environment
 
-- Required environment variables:
+- Required environment variables (on the backend container):
 
   - `FIREBASE_API_KEY`: Web API key from Firebase Console