Improve Docker-Compose Install Experience #9781

john-s4d · 2025-01-21T19:58:15Z

This PR updates the docker-compose installation documentation and env sample to improve the setup experience.

Updates the URLs for raw files to reference main branch, which is likely where new users will be pulling from initially. This seems to be the most straightforward option; assume that advanced users who want to retrieve it from a particular tag will know to change the URL for their scenario.
Fixes an improperly stated curl command.
Adds a note that the PGPASSWORD_SUPERUSER should be URL-safe. This is required since the value is later concat into a PG_DATABASE_URL as a URL, and expected to be in proper URL format. Touches on PostgreSQL Password with Special Characters Leads to isUrl Validation Failure #8597.

greptile-apps

PR Summary

This PR enhances the Docker Compose installation documentation and environment configuration, focusing on PostgreSQL connection settings and user guidance.

Added port specification (5432) to PG_DATABASE_HOST in /packages/twenty-docker/.env.example to prevent connection issues
Added explicit warning about URL-safe PostgreSQL passwords in documentation to prevent validation failures
Updated raw file URLs in documentation to reference main branch for better initial setup experience
Fixed curl command syntax in Docker Compose installation guide for proper file retrieval

_{💡 (1/5) You can manually trigger the bot by mentioning @greptileai in a comment!}

_{2 file(s) reviewed, no comment(s)}
_{Edit PR Review Bot Settings | Greptile}

into docker-compose-docs

FelixMalfait

Hey @john-s4d, thanks a lot for helping others self-host more easily! Made minor comments

FelixMalfait · 2025-01-22T08:26:28Z

packages/twenty-docker/.env.example

-#PGPASSWORD_SUPERUSER=replace_me_with_a_strong_password
-#PG_DATABASE_HOST=db
+#PGPASSWORD_SUPERUSER=replace_me_with_a_url-safe_strong_password
+#PG_DATABASE_HOST=db:5432


I think the suggestion in the issue was rather to keep PG_DATABASE_HOST=db but enforce port 5432 in the docker-compose, I think this make more sense (people don't expect to put the port in the host variable)

Just saw the PR description, If you want port to be configurable in .env then you can add it as a new variable (PG_DATABASE_PORT). But I don't know if there is that much use for it since this is an internal port and it is not exposed publicly on that port, it could confuse users

I think there are scenarios where self-hosted will want to change the DB port, and I agree the ideal solution is to create a var PG_DATABASE_PORT. However, it's a bigger change, and I wasn't able to actually reproduce the original complaint in #9615 . So I think it's better to handle that in a new PR. I'll revert this part.

FelixMalfait · 2025-01-22T08:31:17Z

packages/twenty-docker/docker-compose.yml

@@ -21,7 +21,7 @@ services:
      - "3000:3000"
    environment:
      PORT: 3000
-      PG_DATABASE_URL: postgres://${PGUSER_SUPERUSER:-postgres}:${PGPASSWORD_SUPERUSER:-postgres}@${PG_DATABASE_HOST:-db:5432}/default
+      PG_DATABASE_URL: "postgres://${PGUSER_SUPERUSER:-postgres}:${PGPASSWORD_SUPERUSER:-postgres}@${PG_DATABASE_HOST:-db:5432}/default"


(as per previous comment) I think ${PG_DATABASE_HOST:-db}:5432 would be best

FelixMalfait

Thanks a lot! I made a commit on your branch to ship to fix asap but open to discussion if you disagree!

charlesBochet · 2025-01-22T09:51:35Z

packages/twenty-docker/.env.example

@@ -1,7 +1,7 @@
 TAG=latest

 #PGUSER_SUPERUSER=postgres
-#PGPASSWORD_SUPERUSER=replace_me_with_a_strong_password
+#PGPASSWORD_SUPERUSER=replace_me_with_a_url-safe_strong_password


case: url-safe => url_safe

to me "url safe" is not a standard wording, I googled it and got no result. I did not understand it upon reading the first time
url escaped? not sure it's super clear either

More specifically these characters must be avoided: % @ ! # $ &
URL-Escaped (ie: @ -> %40) also doesn't work, which is surprising to me, but perhaps a deeper issue.
The phrase "without special characters" seems like a reasonable fix.

charlesBochet · 2025-01-22T09:53:10Z

packages/twenty-docker/scripts/install.sh

-# Issue with Postgres spilo?
-#echo "" >>.env
-#echo "PGPASSWORD_SUPERUSER=$(openssl rand -hex 16)" >>.env
+echo "" >>.env


charlesBochet · 2025-01-22T09:53:24Z

packages/twenty-docker/scripts/install.sh

-#echo "" >>.env
-#echo "PGPASSWORD_SUPERUSER=$(openssl rand -hex 16)" >>.env
+echo "" >>.env
+echo "PGPASSWORD_SUPERUSER=$(openssl rand -hex 16)" >>.env


same here :)

charlesBochet · 2025-01-22T09:53:48Z

packages/twenty-website/src/content/developers/self-hosting/docker-compose.mdx

@@ -65,7 +65,7 @@ Follow these steps for a manual setup.

 4. **Set the Postgres Password**

-    Update the `PGPASSWORD_SUPERUSER` value in the .env file with a strong password.
+    Update the `PGPASSWORD_SUPERUSER` value in the .env file with a strong password that is URL-safe.


same note here on "URL-safe" wording

charlesBochet

Thanks @john-s4d! I have left a few comments too

This PR updates the docker-compose installation documentation and env sample to improve the setup experience. - Updates the URLs for raw files to reference main branch, which is likely where new users will be pulling from initially. This seems to be the most straightforward option; assume that advanced users who want to retrieve it from a particular tag will know to change the URL for their scenario. - Fixes an improperly stated curl command. - Adds a note that the PGPASSWORD_SUPERUSER should be URL-safe. This is required since the value is later concat into a PG_DATABASE_URL as a URL, and expected to be in proper URL format. Touches on twentyhq#8597. --------- Co-authored-by: Félix Malfait <[email protected]> Co-authored-by: Félix Malfait <[email protected]>

john-s4d and others added 2 commits January 21, 2025 14:53

improve docker-compose install doc

e2f83f3

Merge branch 'main' into docker-compose-docs

0adb4dc

greptile-apps bot reviewed Jan 21, 2025

View reviewed changes

john-s4d added 2 commits January 21, 2025 15:34

handling PG_DATABASE_URL better in docker-compose

b16065b

Merge branch 'docker-compose-docs' of https://github.com/john-s4d/twenty

6beef3f

into docker-compose-docs

FelixMalfait reviewed Jan 22, 2025

View reviewed changes

FelixMalfait added the -PR: awaiting author label Jan 22, 2025

Address review comments

4884d3b

FelixMalfait approved these changes Jan 22, 2025

View reviewed changes

FelixMalfait enabled auto-merge (squash) January 22, 2025 09:33

charlesBochet reviewed Jan 22, 2025

View reviewed changes

charlesBochet requested changes Jan 22, 2025

View reviewed changes

FelixMalfait disabled auto-merge January 22, 2025 10:00

Charles PR comment

6578d4e

FelixMalfait enabled auto-merge (squash) January 22, 2025 10:10

FelixMalfait and others added 2 commits January 22, 2025 11:11

Ultimate fix

b9c9a64

revert PG_DATABASE_URL interpolation

a3fb85b

auto-merge was automatically disabled January 22, 2025 14:36
Head branch was pushed to by a user without write access

john-s4d requested a review from charlesBochet January 22, 2025 14:38

john-s4d and others added 4 commits January 22, 2025 15:45

Merge branch 'twentyhq:main' into docker-compose-docs

1c7b42c

Introduce database port

9ee000e

Install script

f09debc

Merge branch 'main' into docker-compose-docs

1751679

FelixMalfait merged commit 25cb909 into twentyhq:main Jan 24, 2025
30 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve Docker-Compose Install Experience #9781

Improve Docker-Compose Install Experience #9781

john-s4d commented Jan 21, 2025 •

edited

Loading

greptile-apps bot left a comment

FelixMalfait left a comment

FelixMalfait Jan 22, 2025

FelixMalfait Jan 22, 2025 •

edited

Loading

john-s4d Jan 22, 2025

FelixMalfait Jan 22, 2025

FelixMalfait left a comment

charlesBochet Jan 22, 2025

john-s4d Jan 22, 2025

charlesBochet Jan 22, 2025 •

edited

Loading

charlesBochet Jan 22, 2025

charlesBochet Jan 22, 2025

charlesBochet left a comment

Improve Docker-Compose Install Experience #9781

Improve Docker-Compose Install Experience #9781

Conversation

john-s4d commented Jan 21, 2025 • edited Loading

greptile-apps bot left a comment

Choose a reason for hiding this comment

PR Summary

FelixMalfait left a comment

Choose a reason for hiding this comment

FelixMalfait Jan 22, 2025

Choose a reason for hiding this comment

FelixMalfait Jan 22, 2025 • edited Loading

Choose a reason for hiding this comment

john-s4d Jan 22, 2025

Choose a reason for hiding this comment

FelixMalfait Jan 22, 2025

Choose a reason for hiding this comment

FelixMalfait left a comment

Choose a reason for hiding this comment

charlesBochet Jan 22, 2025

Choose a reason for hiding this comment

john-s4d Jan 22, 2025

Choose a reason for hiding this comment

charlesBochet Jan 22, 2025 • edited Loading

Choose a reason for hiding this comment

charlesBochet Jan 22, 2025

Choose a reason for hiding this comment

charlesBochet Jan 22, 2025

Choose a reason for hiding this comment

charlesBochet left a comment

Choose a reason for hiding this comment

john-s4d commented Jan 21, 2025 •

edited

Loading

FelixMalfait Jan 22, 2025 •

edited

Loading

charlesBochet Jan 22, 2025 •

edited

Loading