Website - Readme update (#8712)

### Readme ideas for better getting started Website update proposal to give an easier way to get started on the Local Setup --------- Co-authored-by: guillim <[email protected]>
twentyhq · Nov 25, 2024 · 2e2b279 · 2e2b279
1 parent 8c7d1f9
commit 2e2b279
Show file tree

Hide file tree

Showing 3 changed files with 46 additions and 15 deletions.
diff --git a/packages/twenty-website/README.md b/packages/twenty-website/README.md
@@ -7,15 +7,16 @@ This is not related in anyway to the main app, which you can find in twenty-fron
 ## Getting Started
 
 We're using Next.JS
+We're using Postgres for the database. Mandatory for the website to work, even locally.
 
-Copy the .env.example file to .env and fill in the values.
+1. Copy the .env.example file to .env and fill in the values.
 
-Run the migrations:
+2. Run the migrations:
 ```bash
 npx nx run twenty-website:database:migrate
 ```
 
-From the root directory:
+3. From the root directory:
 ```bash
 npx nx run twenty-website:dev
 ```

diff --git a/packages/twenty-website/src/content/developers/local-setup.mdx b/packages/twenty-website/src/content/developers/local-setup.mdx
@@ -2,11 +2,9 @@
 title: Local Setup
 icon: TbDeviceDesktop
 image: /images/user-guide/fields/field.png
-info: Mostly for contributors or curious developers
+info: The guide for contributors (or curious developers) who want to run Twenty locally (on laptop, PC...)
 ---
 
-Follow this guide if you would like to set up the project locally to contribute.
-
 ## Prerequisites
 
 <ArticleTabs label1="Linux and MacOS" label2="Windows (WSL)">
@@ -105,11 +103,10 @@ cd twenty
 You should run all commands in the following steps from the root of the project.
 
 ## Step 3: Set up a PostgreSQL Database
-You can access the database at [localhost:5432](localhost:5432), with user `twenty` and password `twenty` .
 
 <ArticleTabs label1="Linux" label2="Mac OS" label3="Windows (WSL)">
   <ArticleTab>
-    <b>Option 1:</b> To provision your database locally:
+    <b>Option 1 (preferred):</b> To provision your database locally:
     Use the following link to install Postgresql on your Linux machine: [Postgresql Installation](https://www.postgresql.org/download/linux/)
     ```bash
       psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;" -c "CREATE USER twenty PASSWORD 'twenty';" -c "ALTER ROLE twenty superuser;"
@@ -122,7 +119,7 @@ You can access the database at [localhost:5432](localhost:5432), with user `twen
     ```
   </ArticleTab>
   <ArticleTab>
-    <b>Option 1:</b> To provision your database locally with `brew`:
+    <b>Option 1 (preferred):</b> To provision your database locally with `brew`:
 
     ```bash
       brew install postgresql@16
@@ -154,8 +151,10 @@ You can access the database at [localhost:5432](localhost:5432), with user `twen
   </ArticleTab>
 </ArticleTabs>
 
+You can now access the database at [localhost:5432](localhost:5432), with user `twenty` and password `twenty` .
+
 ## Step 4: Set up a Redis Database (cache)
-Twenty requires a redis cache to provide the best performances
+Twenty requires a redis cache to provide the best performance
 
 <ArticleTabs label1="Linux" label2="Mac OS" label3="Windows (WSL)">
   <ArticleTab>
@@ -168,10 +167,12 @@ Twenty requires a redis cache to provide the best performances
     ```
   </ArticleTab>
   <ArticleTab>
-    <b>Option 1:</b> To provision your Redis locally with `brew`:
+    <b>Option 1 (preferred):</b> To provision your Redis locally with `brew`:
     ```bash
     brew install redis
     ```
+    Start your redis server:
+    ```brew services start redis```
 
     <b>Option 2:</b> If you have docker installed:
     ```bash
@@ -189,9 +190,11 @@ Twenty requires a redis cache to provide the best performances
   </ArticleTab>
 </ArticleTabs>
 
+If you need a Client GUI, we recommend [redis insight](https://redis.io/insight/) (free version available)
+
 ## Step 5: Setup environment variables
 
-Use environment variables or `.env` files to configure your project.
+Use environment variables or `.env` files to configure your project. More info [here](https://twenty.com/developers/section/self-hosting/self-hosting-var)
 
 Copy the `.env.example` files in `/front` and `/server`:
 ```bash
@@ -204,16 +207,17 @@ To build Twenty server and seed some data into your database, run the following
 ```bash
 yarn
 ```
+Note that `npm` or `pnpm` won't work
 
 ## Step 7: Running the project
 
-Start your redis server:
 <ArticleTabs label1="Linux" label2="Mac OS" label3="Windows (WSL)">
   <ArticleTab>
     Depending on your Linux distribution, Redis server might be started automatically.
     If not, check the [Redis installation guide](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) for your distro.
   </ArticleTab>
   <ArticleTab>
+  Redis should already be running. If not, run:
     ```bash
     brew services start redis
     ```
@@ -242,9 +246,20 @@ Alternatively, you can start all services at once:
 npx nx start
 ```
 
-Twenty's server will be up and running at [http://localhost:3000](http://localhost:3000). The GraphQL API can be accessed at [http://localhost:3000/graphql](http://localhost:3000/graphql), and the REST API can be reached at [http://localhost:3000/rest](http://localhost:3000/rest).
+## Step 8: Use Twenty
+
+**Frontend**  
+
+Twenty's frontend will be running at [http://localhost:3001](http://localhost:3001).  
+You can log in using the default demo account: `[email protected]` (password: `Applecar2025`)
+
+**Backend**  
+
+- Twenty's server will be up and running at [http://localhost:3000](http://localhost:3000) 
+- The GraphQL API can be accessed at [http://localhost:3000/graphql](http://localhost:3000/graphql)
+- The REST API can be reached at [http://localhost:3000/rest](http://localhost:3000/rest)
+
 
-Twenty's frontend will be running at [http://localhost:3001](http://localhost:3001). Just log in using the seeded demo account: `[email protected]` (password: `Applecar2025`) to start using Twenty.
 
 ## Troubleshooting
 

diff --git a/packages/twenty-website/src/content/developers/self-hosting/troubleshooting.mdx b/packages/twenty-website/src/content/developers/self-hosting/troubleshooting.mdx
@@ -51,10 +51,25 @@ This should work out of the box with the eslint extension installed. If this doe
 
 In `packages/twenty-front/.env` uncomment `VITE_DISABLE_TYPESCRIPT_CHECKER=true` and `VITE_DISABLE_ESLINT_CHECKER=true` to disable background checks thus reducing amount of needed RAM.
 
+**If it does not work:**  
+Run only the services you need, instead of `npx nx start`. For instance, if you work on the server, run only `npx nx worker twenty-server`
+
+**If it does not work:**  
+Investigate which processes are taking you most of your machine RAM. At Twenty, we noticed that some VScode extensions were taking a lot of RAM so we temporarily disable them. 
+
+**If it does not work:**  
+Restart your machine helps to clean up ghost processes.
+
 #### While running `npx nx start` there are weird [0] and [1] in logs
 
 That's expected as command `npx nx start` is running more commands under the hood
 
+#### No emails are sent
+Most of the time, it's because the `worker` is not running in the background. Try to run 
+```
+npx nx worker twenty-server
+```
+
 #### While running `yarn` warnings appear in console
 
 Warnings are informing about pulling additional dependencies which aren't explicitly stated in `package.json`, so as long as no breaking error appears, everything should work as expected.