mirror of
https://github.com/twentyhq/twenty.git
synced 2024-12-25 13:02:15 +03:00
Improve docs (#5492)
Fix #4382 and remove useless pages to make docs more readable
This commit is contained in:
Félix Malfait
GitHub
parent
a9813447f3
commit
4907ae5a74
@ -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
|
||||
|
||||
226
packages/twenty-docs/docs/start/local-setup.mdx
Normal file
226
packages/twenty-docs/docs/start/local-setup.mdx
Normal file
@ -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
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="yarn" label="Linux and MacOS" default>
|
||||
|
||||
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.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="wsl" label="Windows (WSL)" >
|
||||
|
||||
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.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Git Clone
|
||||
|
||||
In your terminal, run the following command.
|
||||
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="ssh" label="SSH (Recommended)" default>
|
||||
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
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem value="https" label="HTTPS" >
|
||||
|
||||
```bash
|
||||
git clone https://github.com/twentyhq/twenty.git
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 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` .
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="linux" label="Linux" default>
|
||||
<b>Option 1:</b> To provision your database locally:
|
||||
```bash
|
||||
make postgres-on-linux
|
||||
```
|
||||
|
||||
<b>Option 2:</b> If you have docker installed:
|
||||
```bash
|
||||
make postgres-on-docker
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem value="mac-os" label="Mac OS" default>
|
||||
<b>Option 1:</b> 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
|
||||
```
|
||||
|
||||
<b>Option 2:</b> If you have docker installed:
|
||||
```bash
|
||||
make postgres-on-docker
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem value="wsl" label="Windows (WSL)">
|
||||
<b>Option 1 :</b> 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.
|
||||
|
||||
<b>Option 2:</b> 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
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
## 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.
|
||||
@ -1,9 +0,0 @@
|
||||
{
|
||||
"label": "Local setup",
|
||||
"position": 3,
|
||||
"collapsible": true,
|
||||
"collapsed": true,
|
||||
"customProps": {
|
||||
"icon": "TbDeviceDesktop"
|
||||
}
|
||||
}
|
||||
@ -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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/img/contributor/ide-project-open.png" alt="Visual Studio Code: Open Twenty project" width="90%" />
|
||||
</div>
|
||||
|
||||
### 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.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/img/contributor/ide-extensions.png" alt="Visual Studio Code: Install recommended extensions" width="90%" />
|
||||
</div>
|
||||
|
||||
## 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).
|
||||
@ -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.
|
||||
|
||||
<DocCardList/>
|
||||
|
||||
## 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.
|
||||
___
|
||||
|
||||
@ -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.
|
||||
@ -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
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="yarn" label="Linux and MacOS" default>
|
||||
|
||||
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.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="wsl" label="Windows (WSL)" >
|
||||
|
||||
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.
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## 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).
|
||||
|
||||
:::
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="ssh" label="SSH (Recommended)" default>
|
||||
|
||||
```bash
|
||||
git clone git@github.com:twentyhq/twenty.git
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem value="https" label="HTTPS" >
|
||||
|
||||
```bash
|
||||
git clone https://github.com/twentyhq/twenty.git
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 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:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="linux" label="Linux" default>
|
||||
<b>Option 1:</b> To provision your database locally:
|
||||
```bash
|
||||
make postgres-on-linux
|
||||
```
|
||||
|
||||
<b>Option 2:</b> 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`)
|
||||
</TabItem>
|
||||
<TabItem value="mac-os" label="Mac OS" default>
|
||||
|
||||
<b>Option 1:</b> To provision your database locally:
|
||||
```bash
|
||||
make postgres-on-macos-intel #for intel architecture
|
||||
make postgres-on-macos-arm #for M1/M2/M3 architecture
|
||||
```
|
||||
|
||||
<b>Option 2:</b> 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`)
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="wsl" label="Windows (WSL)">
|
||||
|
||||
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`)
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
## 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.
|
||||
@ -1,5 +1,5 @@
|
||||
{
|
||||
"position": 2,
|
||||
"position": 3,
|
||||
"collapsible": true,
|
||||
"collapsed": true
|
||||
}
|
||||
|
||||
@ -31,7 +31,6 @@ const sidebars = {
|
||||
id: 'homepage',
|
||||
customProps: {
|
||||
type: 'search-bar',
|
||||
props: { name: 'Hello World', age: 42 },
|
||||
},
|
||||
},
|
||||
{ type: 'autogenerated', dirName: '.' },
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user