Merge pull request #782 from automatisch/docs/docker-installation

docs: Docker installation

README.md

@@ -30,10 +30,10 @@ git clone git@github.com:automatisch/automatisch.git
 cd automatisch
 
 # Start
-docker compose -p automatisch up
+docker compose up
 ```
 
-You can use `user@automatisch.io` email address and `sample` password to login to Automatisch. You can also change your email and password later on from the settings page.
+You can use `user@automatisch.io` email address and `sample` password to login to Automatisch. Please do not forget to change your email and password from the settings page.
 
 ## Community Links
 

docker-compose.yml

@@ -23,6 +23,7 @@ services:
       - POSTGRES_USERNAME=automatisch_user
       - POSTGRES_PASSWORD=automatisch_password
       - ENCRYPTION_KEY
+      - WEBHOOK_SECRET_KEY
       - APP_SECRET_KEY
     volumes:
       - automatisch_storage:/automatisch/storage
@@ -41,6 +42,7 @@ services:
       - POSTGRES_USERNAME=automatisch_user
       - POSTGRES_PASSWORD=automatisch_password
       - ENCRYPTION_KEY
+      - WEBHOOK_SECRET_KEY
       - APP_SECRET_KEY
       - WORKER=true
     volumes:

docker/compose-entrypoint.sh

@@ -5,14 +5,22 @@ set -e
 if [ ! -f /automatisch/storage/.env ]; then
   >&2 echo "Saving environment variables"
   ENCRYPTION_KEY="${ENCRYPTION_KEY:-$(openssl rand -base64 36)}"
+  WEBHOOK_SECRET_KEY="${WEBHOOK_SECRET_KEY:-$(openssl rand -base64 36)}"
   APP_SECRET_KEY="${APP_SECRET_KEY:-$(openssl rand -base64 36)}"
   echo "ENCRYPTION_KEY=$ENCRYPTION_KEY" >> /automatisch/storage/.env
+  echo "WEBHOOK_SECRET_KEY=$WEBHOOK_SECRET_KEY" >> /automatisch/storage/.env
   echo "APP_SECRET_KEY=$APP_SECRET_KEY" >> /automatisch/storage/.env
 fi
 
 # initiate env. vars. from /automatisch/storage/.env file
 export $(grep -v '^#' /automatisch/storage/.env | xargs)
 
+# migration for webhook secret key, will be removed in the future.
+if [[ -z "${WEBHOOK_SECRET_KEY}" ]]; then
+  WEBHOOK_SECRET_KEY="$(openssl rand -base64 36)"
+  echo "WEBHOOK_SECRET_KEY=$WEBHOOK_SECRET_KEY" >> /automatisch/storage/.env
+fi
+
 echo "Environment variables have been set!"
 
 sh /entrypoint.sh

packages/backend/.env-example

@@ -11,6 +11,7 @@ POSTGRES_USERNAME=automatish_development_user
 POSTGRES_PASSWORD=
 POSTGRES_ENABLE_SSL=false
 ENCRYPTION_KEY=sample-encryption-key
+WEBHOOK_SECRET_KEY=sample-webhook-key
 APP_SECRET_KEY=sample-app-secret-key
 REDIS_PORT=6379
 REDIS_HOST=127.0.0.1

packages/backend/src/apps/typeform/auth/verify-webhook.ts

@@ -11,7 +11,7 @@ const verifyWebhook = async ($: IGlobalVariable) => {
 
 const verifySignature = function (receivedSignature: string, payload: string) {
   const hash = crypto
-    .createHmac('sha256', appConfig.appSecretKey)
+    .createHmac('sha256', appConfig.webhookSecretKey)
     .update(payload)
     .digest('base64');
   return receivedSignature === `sha256=${hash}`;

packages/backend/src/apps/typeform/triggers/new-entry/index.ts

@@ -72,7 +72,7 @@ export default defineTrigger({
     const subscriptionPayload = {
       enabled: true,
       url: $.webhookUrl,
-      secret: appConfig.appSecretKey,
+      secret: appConfig.webhookSecretKey,
     };
 
     await $.http.put(

packages/backend/src/config/app.ts

@@ -18,6 +18,7 @@ type AppConfig = {
   postgresEnableSsl: boolean;
   baseUrl: string;
   encryptionKey: string;
+  webhookSecretKey: string;
   appSecretKey: string;
   serveWebAppSeparately: boolean;
   redisHost: string;
@@ -63,6 +64,7 @@ const appConfig: AppConfig = {
   postgresPassword: process.env.POSTGRES_PASSWORD,
   postgresEnableSsl: process.env.POSTGRES_ENABLE_SSL === 'true',
   encryptionKey: process.env.ENCRYPTION_KEY || '',
+  webhookSecretKey: process.env.WEBHOOK_SECRET_KEY || '',
   appSecretKey: process.env.APP_SECRET_KEY || '',
   serveWebAppSeparately,
   redisHost: process.env.REDIS_HOST || '127.0.0.1',
@@ -70,8 +72,7 @@ const appConfig: AppConfig = {
   redisUsername: process.env.REDIS_USERNAME,
   redisPassword: process.env.REDIS_PASSWORD,
   redisTls: process.env.REDIS_TLS === 'true',
-  enableBullMQDashboard:
+  enableBullMQDashboard: process.env.ENABLE_BULLMQ_DASHBOARD === 'true',
-    process.env.ENABLE_BULLMQ_DASHBOARD === 'true',
   bullMQDashboardUsername: process.env.BULLMQ_DASHBOARD_USERNAME,
   bullMQDashboardPassword: process.env.BULLMQ_DASHBOARD_PASSWORD,
   baseUrl,
@@ -84,4 +85,8 @@ if (!appConfig.encryptionKey) {
   throw new Error('ENCRYPTION_KEY environment variable needs to be set!');
 }
 
+if (!appConfig.webhookSecretKey) {
+  throw new Error('WEBHOOK_SECRET_KEY environment variable needs to be set!');
+}
+
 export default appConfig;

packages/docs/pages/advanced/configuration.md

@@ -11,11 +11,11 @@ The default values for some environment variables might be different in our deve
 :::
 
 :::danger
-Please be careful with the `ENCRYPTION_KEY` environment variable. It is used to encrypt your credentials from third-party services. If you change it, you will not be able to access your connections and thus, your existing flows and connections will be useless.
+Please be careful with the `ENCRYPTION_KEY` and `WEBHOOK_SECRET_KEY` environment variables. They are used to encrypt your credentials from third-party services and verify webhook requests. If you change them, your existing connections and flows will not continue to work.
 :::
 
 | Variable Name               | Type    | Default Value      | Description                                   |
-| --------------------------- | ------- | ------------------ | ----------------------------------- |
+| --------------------------- | ------- | ------------------ | --------------------------------------------- |
 | `HOST`                      | string  | `localhost`        | HTTP Host                                     |
 | `PROTOCOL`                  | string  | `http`             | HTTP Protocol                                 |
 | `PORT`                      | string  | `3000`             | HTTP Port                                     |
@@ -26,6 +26,7 @@ Please be careful with the `ENCRYPTION_KEY` environment variable. It is used to
 | `POSTGRES_USERNAME`         | string  | `automatisch_user` | Database User                                 |
 | `POSTGRES_PASSWORD`         | string  |                    | Password of Database User                     |
 | `ENCRYPTION_KEY`            | string  |                    | Encryption Key to store credentials           |
+| `WEBHOOK_SECRET_KEY`        | string  |                    | Webhook Secret Key to verify webhook requests |
 | `APP_SECRET_KEY`            | string  |                    | Secret Key to authenticate the user           |
 | `REDIS_HOST`                | string  | `redis`            | Redis Host                                    |
 | `REDIS_PORT`                | number  | `6379`             | Redis Port                                    |

packages/docs/pages/advanced/credentials.md

@@ -5,5 +5,5 @@ We need to store your credentials in order to automatically communicate with thi
 Automatisch uses AES specification to encrypt and decrypt your credentials of third-party services. The Advanced Encryption Standard (AES) is a U.S. Federal Information Processing Standard (FIPS). It was selected after a 5-year process where 15 competing designs were evaluated. AES is now used worldwide to protect sensitive information.
 
 :::danger
-Please be careful with the `ENCRYPTION_KEY` environment variable. It is used to encrypt your credentials from third-party services. If you change it, you will not be able to access your connections and thus, your existing flows and connections will be useless.
+Please be careful with the `ENCRYPTION_KEY` and `WEBHOOK_SECRET_KEY` environment variables. They are used to encrypt your credentials from third-party services and verify webhook requests. If you change them, your existing connections and flows will not continue to work.
 :::

packages/docs/pages/guide/installation.md

@@ -1,6 +1,20 @@
 # Installation
 
-You can install Automatisch by using docker compose.
+:::info
+We have installation guides for docker compose and docker setup at the moment, but if you need another installation type, let us know by [creating a GitHub issue](https://github.com/automatisch/automatisch/issues/new).
+:::
+
+:::tip
+
+You can use `user@automatisch.io` email address and `sample` password to login to Automatisch. Please do not forget to change your email and password from the settings page.
+
+:::
+
+:::danger
+Please be careful with the `ENCRYPTION_KEY` and `WEBHOOK_SECRET_KEY` environment variables. They are used to encrypt your credentials from third-party services and verify webhook requests. If you change them, your existing connections and flows will not continue to work.
+:::
+
+## Docker Compose
 
 ```bash
 # Clone the repository
@@ -10,17 +24,60 @@ git clone git@github.com:automatisch/automatisch.git
 cd automatisch
 
 # Start
-docker compose -p automatisch up
+docker compose up
 ```
 
-## Let's discover!
+✌️ That's it; you have Automatisch running. Let's check it out by browsing [http://localhost:3000](https://localhost:3000)
 
-✌️ That's it; you have Automatisch running. Let's check it out by browsing `http://localhost:3000`
+## Docker
 
-:::tip
+Automatisch comes with two services which are `main` and `worker`. They both use the same image and need to have the same environment variables except for the `WORKER` environment variable which is set to `true` for the worker service.
 
-You can use `user@automatisch.io` email address and `sample` password to login to Automatisch. You can also change your email and password later on from the settings page.
+::: warning
+We give the sample environment variable files for the setup but you should adjust them to include your own values.
+:::
+
+To run the main:
+
+```bash
+docker run --env-file=./.env automatischio/automatisch
+```
+
+To run the worker:
+
+```bash
+docker run --env-file=./.env -e WORKER=true automatischio/automatisch
+```
+
+::: details .env
+
+```bash
+APP_ENV=production
+HOST=
+PROTOCOL=
+PORT=
+ENCRYPTION_KEY=
+WEBHOOK_SECRET_KEY=
+APP_SECRET_KEY=
+POSTGRES_HOST=
+POSTGRES_PORT=
+POSTGRES_DATABASE=
+POSTGRES_USERNAME=
+POSTGRES_PASSWORD=
+POSTGRES_ENABLE_SSL=
+REDIS_HOST=
+REDIS_PORT=
+REDIS_USERNAME=
+REDIS_PASSWORD=
+REDIS_TLS=
+```
 
 :::
 
+## Production setup
+
+If you need to change any other environment variables for your production setup, let's check out the [environment variables](/advanced/configuration#environment-variables) section of the configuration page.
+
+## Let's discover!
+
 If you see any problems while installing Automatisch, let us know via [github issues](https://github.com/automatisch/automatisch/issues) or our [discord server](https://discord.gg/dJSah9CVrC).