From 4907ae5a74bb5657e72231bc3ac5c40999d04f41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Malfait?= Date: Tue, 21 May 2024 09:09:19 +0200 Subject: [PATCH] Improve docs (#5492) Fix #4382 and remove useless pages to make docs more readable --- packages/twenty-docs/docs/index.mdx | 2 +- .../twenty-docs/docs/start/local-setup.mdx | 226 ++++++++++++++++++ .../docs/start/local-setup/_category_.json | 9 - .../docs/start/local-setup/ide-setup.mdx | 39 --- .../docs/start/local-setup/local-setup.mdx | 37 --- .../start/local-setup/troubleshooting.mdx | 45 ---- .../docs/start/local-setup/yarn-setup.mdx | 202 ---------------- .../docs/start/self-hosting/_category_.json | 2 +- packages/twenty-docs/sidebars.js | 1 - packages/twenty-server/.env.example | 2 - 10 files changed, 228 insertions(+), 337 deletions(-) create mode 100644 packages/twenty-docs/docs/start/local-setup.mdx delete mode 100644 packages/twenty-docs/docs/start/local-setup/_category_.json delete mode 100644 packages/twenty-docs/docs/start/local-setup/ide-setup.mdx delete mode 100644 packages/twenty-docs/docs/start/local-setup/local-setup.mdx delete mode 100644 packages/twenty-docs/docs/start/local-setup/troubleshooting.mdx delete mode 100644 packages/twenty-docs/docs/start/local-setup/yarn-setup.mdx diff --git a/packages/twenty-docs/docs/index.mdx b/packages/twenty-docs/docs/index.mdx index 23cf172a91..160b8bbe1e 100644 --- a/packages/twenty-docs/docs/index.mdx +++ b/packages/twenty-docs/docs/index.mdx @@ -12,7 +12,7 @@ import ThemedImage from '@theme/ThemedImage'; Twenty is a CRM designed to fit your unique business needs. -It was brought to life by a passionate community that cares about quality and precision in engineering. +It is maintained by a community of 200+ developers that care about building high-quality software. There are three different ways to get started: - **Managed Cloud:** The fastest and easiest way to try the app diff --git a/packages/twenty-docs/docs/start/local-setup.mdx b/packages/twenty-docs/docs/start/local-setup.mdx new file mode 100644 index 0000000000..b73eda9119 --- /dev/null +++ b/packages/twenty-docs/docs/start/local-setup.mdx @@ -0,0 +1,226 @@ +--- +title: Local Setup +sidebar_position: 2 +sidebar_custom_props: + icon: TbDeviceDesktop +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +Follow this guide if you would like to setup the project locally to contribute. + +## Prerequisites + + + + +Before you can install and use Twenty, make sure you install the following on your computer: +- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +- [Node v18](https://nodejs.org/en/download) +- [yarn v4](https://yarnpkg.com/getting-started/install) +- [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) + +:::info Note +`npm` won't work, you should use `yarn` instead. Yarn is now shipped with Node.js, so you don't need to install it separately. +You only have to run `corepack enable` to enable Yarn if you haven't done it yet. +::: + + + + + +1. Install WSL +Open PowerShell as Administrator and run: + +```powershell +wsl --install +``` +You should now see a prompt to restart your computer. If not, restart it manually. + +Upon restart, a powershell window will open and install Ubuntu. This may take up some time. +You'll see a prompt to create a username and password for your Ubuntu installation. + +2. Install and configure git + +```bash +sudo apt-get install git +git config --global user.name "Your Name" +git config --global user.email "youremail@domain.com" +``` + +3. Install Node.js, nvm, yarn +```bash +sudo apt-get install curl +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash +corepack enable +``` +Close and reopen your terminal to start using nvm. + + + + +--- + +## Step 1: Git Clone + +In your terminal, run the following command. + + + + +If you haven't already set up SSH keys, you can learn how to do so [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh). +```bash +git clone git@github.com:twentyhq/twenty.git +``` + + + +```bash +git clone https://github.com/twentyhq/twenty.git +``` + + + + +## Step 2: Position yourself at the root + +```bash +cd twenty +``` + +You should run all commands in the following steps from the root of the project. + +## Step 3: Set up a PostgreSQL Database +We rely on [pg_graphql](https://github.com/supabase/pg_graphql) and recommend you use the scripts below to provision a database with the right extensions. +You can access the database at [localhost:5432](localhost:5432), with user `twenty` and password `twenty` . + + + + Option 1: To provision your database locally: + ```bash + make postgres-on-linux + ``` + + Option 2: If you have docker installed: + ```bash + make postgres-on-docker + ``` + + + Option 1: To provision your database locally with `brew`: + ```bash + make postgres-on-macos-intel #for intel architecture + make postgres-on-macos-arm #for M1/M2/M3 architecture + ``` + + Option 2: If you have docker installed: + ```bash + make postgres-on-docker + ``` + + + Option 1 : To provision your database locally: + ```bash + make postgres-on-linux + ``` + + Note: you might need to run `sudo apt-get install build-essential` before running the above command if you don't have the build tools installed. + + Option 2: If you have docker installed: + Running Docker on WSL adds an extra layer of complexity. + Only use this option if you are comfortable with the extra steps involved, including turning on [Docker Desktop WSL2](https://docs.docker.com/desktop/wsl). + ```bash + make postgres-on-docker + ``` + + + + +## Step 4: Setup environment variables + +Use environment variables or `.env` files to configure your project. + +Copy the `.env.example` files in `/front` and `/server`: +```bash +cp ./packages/twenty-front/.env.example ./packages/twenty-front/.env +cp ./packages/twenty-server/.env.example ./packages/twenty-server/.env +``` + +## Step 5: Installing dependencies + +:::info + +Use `nvm` to install the correct `node` version. The `.nvmrc` ensures all contributors use the same version. + +::: + +To build Twenty server and seed some data into your database, run the following commands: +```bash +nvm install # installs recommended node version +nvm use # use recommended node version + +yarn +``` + +## Step 6: Running the project + +Setup your database with the following command: +```bash +npx nx database:reset twenty-server +``` + +Start the server and the frontend: +```bash +npx nx start twenty-server +npx nx start twenty-front +``` + +Alternatively, you can start both applications at once: +```bash +npx nx start +``` + +Twenty's server will be up and running at [http://localhost:3000/graphql](http://localhost:3000/graphql). +Twenty's frontend will be running at [http://localhost:3001](http://localhost:3001). Just login using the seeded demo account: `tim@apple.dev` (password: `Applecar2025`) to start using Twenty. + + +## Troubleshooting + +#### CR line breaks found [Windows] + +This is due to the line break characters of Windows and the git configuration. Try running: + +``` +git config --global core.autocrlf false +``` + +Then delete the repository and clone it again. + +#### Missing metadata schema + +During Twenty installation, you need to provision your postgres database with the right schemas, extensions, and users. +If you're successful in running this provisioning, you should have `default` and `metadata` schemas in your database. +If you don't, make sure you don't have more than one postgres instance running on your computer. + +#### Cannot find module 'twenty-emails' or its corresponding type declarations. + +You have to build the package `twenty-emails` before running the initialization of the database with `npx nx run twenty-emails:build` + +#### Missing twenty-x package + +Make sure to run yarn in the root directory and then run `npx nx server:dev twenty-server`. If this still doesn't work try building the missing package manually. + +#### Lint on Save not working + +This should work out of the box with the eslint extension installed. If this doens't work try adding this to your vscode setting (on the dev container scope): + +``` +"editor.codeActionsOnSave": { + "source.fixAll.eslint": "explicit" +} +``` + +#### Docker container build + +To successfully build Docker images, ensure that your system has a minimum of 2GB of memory available. For users of Docker Desktop, please verify that you've allocated sufficient resources to Docker within the application's settings. diff --git a/packages/twenty-docs/docs/start/local-setup/_category_.json b/packages/twenty-docs/docs/start/local-setup/_category_.json deleted file mode 100644 index dd5673939f..0000000000 --- a/packages/twenty-docs/docs/start/local-setup/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "Local setup", - "position": 3, - "collapsible": true, - "collapsed": true, - "customProps": { - "icon": "TbDeviceDesktop" - } -} diff --git a/packages/twenty-docs/docs/start/local-setup/ide-setup.mdx b/packages/twenty-docs/docs/start/local-setup/ide-setup.mdx deleted file mode 100644 index 93c9137298..0000000000 --- a/packages/twenty-docs/docs/start/local-setup/ide-setup.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: IDE Setup -sidebar_position: 4 -description: Get the best developer UX with VSCode -sidebar_custom_props: - icon: TbBrandVscode ---- - -This section will help you set up your IDE for the project. If you haven't set up your development environment, please refer to the [local setup](/start/local-setup) section. - - -## Visual Studio Code - -You can use any IDE you prefer, but Visual Studio Code is the choice of the core team, and has lots of extensions and settings to share with you. - - -### Step 1: Installation - -You can download Visual Studio Code from [here](https://code.visualstudio.com/download). Depending on your operating system, you can download the appropriate version. - -### Step 2: Open Project - -Once you install Visual Studio Code, you can open the project by clicking on `File > Open Folder` and selecting `twenty` project root folder. - -
- Visual Studio Code: Open Twenty project -
- -### Step 3: Extensions - -You can use the recommended extensions for the project. You will find them in `.vscode/extensions.json` file. VSCode should prompt you to install the recommended extensions when you open the project. - -
- Visual Studio Code: Install recommended extensions -
- -## You are all set - -You are all set to start contributing to the project. If you have any questions, feel free to reach out to the team on [Discord](https://discord.gg/cx5n4Jzs57). \ No newline at end of file diff --git a/packages/twenty-docs/docs/start/local-setup/local-setup.mdx b/packages/twenty-docs/docs/start/local-setup/local-setup.mdx deleted file mode 100644 index 6fcab0e376..0000000000 --- a/packages/twenty-docs/docs/start/local-setup/local-setup.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Local Setup -sidebar_position: 0 -sidebar_custom_props: - icon: TbDeviceDesktop ---- -import DocCardList from '@theme/DocCardList'; - - - -Twenty aims for developer-friendliness, and your local installation should be up and running in just a bit. - - - -## Discord - -If you have any questions or need help, you can join Twenty's [Discord](https://discord.gg/cx5n4Jzs57) server. - - -## Project structure - -The repository has the following structure: -``` -twenty -└───packages // contains this documentation -└──────twenty-front // contains the frontend code for the application -└──────twenty-server // contains the backend code for the application -└──────twenty-docker // contains docker configurations for production build -└──────other packages that are less relevant as a first step such (docs, zapier app...) -``` - -## IDE Setup - -Once Twenty is running on your computer, you will get the best experience by using an IDE that supports TypeScript and ESLint. -You will find a guide for [VSCode](/start/local-setup/ide-setup) further in the documentation. -___ - diff --git a/packages/twenty-docs/docs/start/local-setup/troubleshooting.mdx b/packages/twenty-docs/docs/start/local-setup/troubleshooting.mdx deleted file mode 100644 index 23fc30f373..0000000000 --- a/packages/twenty-docs/docs/start/local-setup/troubleshooting.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Troubleshooting -sidebar_position: 5 -description: Common problems & their solutions. -sidebar_custom_props: - icon: TbExclamationCircle ---- - -## CR line breaks found [Windows] - -This is due to the line break characters of Windows and the git configuration. Try running: - -``` -git config --global core.autocrlf false -``` - -Then delete the repository and clone it again. - -## Missing metadata schema - -During Twenty installation, you need to provision your postgres database with the right schemas, extensions, and users. -If you're successful in running this provisioning, you should have `default` and `metadata` schemas in your database. -If you don't, make sure you don't have more than one postgres instance running on your computer. - -## Cannot find module 'twenty-emails' or its corresponding type declarations. - -You have to build the package `twenty-emails` before running the initialization of the database with `npx nx run twenty-emails:build` - -## Missing twenty-x package - -Make sure to run yarn in the root directory and then run `npx nx server:dev twenty-server`. If this still doesn't work try building the missing package manually. - -## Lint on Save not working - -This should work out of the box with the eslint extension installed. If this doens't work try adding this to your vscode setting (on the dev container scope): - -``` -"editor.codeActionsOnSave": { - "source.fixAll.eslint": "explicit" -} -``` - -## Docker container build - -To successfully build Docker images, ensure that your system has a minimum of 2GB of memory available. For users of Docker Desktop, please verify that you've allocated sufficient resources to Docker within the application's settings. diff --git a/packages/twenty-docs/docs/start/local-setup/yarn-setup.mdx b/packages/twenty-docs/docs/start/local-setup/yarn-setup.mdx deleted file mode 100644 index defdb3d314..0000000000 --- a/packages/twenty-docs/docs/start/local-setup/yarn-setup.mdx +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: Yarn Setup -sidebar_position: 1 -description: | - Set up the project with Yarn -sidebar_custom_props: - icon: TbScript ---- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - -:::info -`npm` does not support local packages well, opt for `yarn` instead. -::: - -## Prerequisites - - - - -Before you can install and use Twenty, make sure you install the following on your computer: -- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -- [Node v18](https://nodejs.org/en/download) -- [yarn v4](https://yarnpkg.com/getting-started/install) -- [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) - -:::info Note -Yarn is now shipped with Node.js nowadays, so you don't need to install it separately. -You should only have to run `corepack enable` to enable Yarn if you haven't done it yet. -::: - - - - - -1. Install WSL -Open PowerShell as Administrator and run: - -```powershell -wsl --install -``` -You should now see a prompt to restart your computer. If not, restart it manually. - -Upon restart, a powershell window will open and install Ubuntu. This may take up some time. -You'll see a prompt to create a username and password for your Ubuntu installation. - -2. Install and configure git - -```bash -sudo apt-get install git -git config --global user.name "Your Name" -git config --global user.email "youremail@domain.com" -``` - -3. Install Node.js, nvm, yarn -```bash -sudo apt-get install curl -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash -corepack enable -``` -Close and reopen your terminal to start using nvm. - -:::caution Note - -Avoid using Docker on WSL as it adds an extra layer of complexity. - -::: - - - - ---- - -## Step 1: Git Clone - -In your terminal, run the following command. - -:::info Note - -It's better to use SSH for this step. If you already haven't set up SSH keys, please do so first. You can learn more about it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh). - -::: - - - - -```bash -git clone git@github.com:twentyhq/twenty.git -``` - - - -```bash -git clone https://github.com/twentyhq/twenty.git -``` - - - - -## Step 2: Place yourself at the root of the project - -```bash -cd twenty -``` - -All commands in the following steps should be run from the root of the project. - - -## Step 3: Set up PostgreSQL Database -To install PostgreSQL with a `default` and a `test` database, and provision these databases with a user `twenty` (password: `twenty`), follow the steps below: - - - -Option 1: To provision your database locally: -```bash -make postgres-on-linux -``` - -Option 2: If you have docker installed: -```bash -make postgres-on-docker -``` -This will create a Docker container, exposing a PostgresSQL instance at [http://localhost:5432](http://localhost:5432). -You can access this using `twenty` postgres user (password: `twenty`) - - - -Option 1: To provision your database locally: -```bash -make postgres-on-macos-intel #for intel architecture -make postgres-on-macos-arm #for M1/M2/M3 architecture -``` - -Option 2: If you have docker installed: -```bash -make postgres-on-docker -``` -This will create a Docker container, exposing a PostgresSQL instance at [http://localhost:5432](http://localhost:5432). -You can access this using `twenty` postgres user (password: `twenty`) - - - - -It's better to provision your database locally: -```bash -make postgres-on-linux -``` -This will create a Docker container, exposing a PostgresSQL instance at [http://localhost:5432](http://localhost:5432). -You can access this using `twenty` postgres user (password: `twenty`) - - - - -## Step 4: Setup environment variables - -Twenty requires you to set some environment variables. Locally, you should set them through a `.env` file. - -To do so, make copies of the `.env.example` files in `/front` and `/server`: -```bash -cp ./packages/twenty-front/.env.example ./packages/twenty-front/.env -cp ./packages/twenty-server/.env.example ./packages/twenty-server/.env -``` - -## Step 5: Installing dependencies - -:::info - -Use `nvm` to install the correct `node` version. The `.nvmrc` ensures all contributors use the same version. - -::: - -To build Twenty server and seed some data into your database, run the following commands: -```bash -nvm install #recommended -nvm use #recommended - -yarn -``` - -## Step 6: Running the project - -Setup your database with the following command: -```bash -npx nx database:reset twenty-server -``` - -Start the server and the frontend: -```bash -npx nx start twenty-server -npx nx start twenty-front -``` - -Alternatively, you can start both applications at once: -```bash -npx nx start -# or -npx nx start twenty -``` - -Twenty's server will be up and running at [http://localhost:3000/graphql](http://localhost:3000/graphql). -Twenty's frontend will be running at [http://localhost:3001](http://localhost:3001). Just login using the seeded demo account: `tim@apple.dev` (password: `Applecar2025`) to start using Twenty. diff --git a/packages/twenty-docs/docs/start/self-hosting/_category_.json b/packages/twenty-docs/docs/start/self-hosting/_category_.json index e82cbee64b..254ec2489a 100644 --- a/packages/twenty-docs/docs/start/self-hosting/_category_.json +++ b/packages/twenty-docs/docs/start/self-hosting/_category_.json @@ -1,5 +1,5 @@ { - "position": 2, + "position": 3, "collapsible": true, "collapsed": true } diff --git a/packages/twenty-docs/sidebars.js b/packages/twenty-docs/sidebars.js index 99a9a5a031..2a6ec4fa17 100644 --- a/packages/twenty-docs/sidebars.js +++ b/packages/twenty-docs/sidebars.js @@ -31,7 +31,6 @@ const sidebars = { id: 'homepage', customProps: { type: 'search-bar', - props: { name: 'Hello World', age: 42 }, }, }, { type: 'autogenerated', dirName: '.' }, diff --git a/packages/twenty-server/.env.example b/packages/twenty-server/.env.example index e3e0a91121..058fd43005 100644 --- a/packages/twenty-server/.env.example +++ b/packages/twenty-server/.env.example @@ -1,7 +1,5 @@ # Use this for local setup PG_DATABASE_URL=postgres://twenty:twenty@localhost:5432/default -# Use this for docker setup -# PG_DATABASE_URL=postgres://twenty:twenty@postgres:5432/default FRONT_BASE_URL=http://localhost:3001