admin/twenty
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Improve docs (#5492)

Browse Source 
Fix #4382 and remove useless pages to make docs more readable
This commit is contained in:
Félix Malfait
2024-05-21 09:09:19 +02:00
committed by GitHub
parent a9813447f3
commit 4907ae5a74
10 changed files with 228 additions and 337 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/twenty-docs/docs/index.mdx
View File

@ -12,7 +12,7 @@ import ThemedImage from '@theme/ThemedImage';
Twenty is a CRM designed to fit your unique business needs. 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: There are three different ways to get started:
- **Managed Cloud:** The fastest and easiest way to try the app - **Managed Cloud:** The fastest and easiest way to try the app

226
packages/twenty-docs/docs/start/local-setup.mdx Normal file
View 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.

9
packages/twenty-docs/docs/start/local-setup/_category_.json
View File

@ -1,9 +0,0 @@
{
"label": "Local setup",
"position": 3,
"collapsible": true,
"collapsed": true,
"customProps": {
"icon": "TbDeviceDesktop"
}
}

39
packages/twenty-docs/docs/start/local-setup/ide-setup.mdx
View File

@ -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).

37
packages/twenty-docs/docs/start/local-setup/local-setup.mdx
View File

@ -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.
___

45
packages/twenty-docs/docs/start/local-setup/troubleshooting.mdx
View File

@ -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.

202
packages/twenty-docs/docs/start/local-setup/yarn-setup.mdx
View File

@ -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.

2
packages/twenty-docs/docs/start/self-hosting/_category_.json
View File

@ -1,5 +1,5 @@
{ {
"position": 2, "position": 3,
"collapsible": true, "collapsible": true,
"collapsed": true "collapsed": true
} }

1
packages/twenty-docs/sidebars.js
View File

@ -31,7 +31,6 @@ const sidebars = {
id: 'homepage', id: 'homepage',
customProps: { customProps: {
type: 'search-bar', type: 'search-bar',
props: { name: 'Hello World', age: 42 },
}, },
}, },
{ type: 'autogenerated', dirName: '.' }, { type: 'autogenerated', dirName: '.' },

2
packages/twenty-server/.env.example
View File

@ -1,7 +1,5 @@
# Use this for local setup # Use this for local setup
PG_DATABASE_URL=postgres://twenty:twenty@localhost:5432/default 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 FRONT_BASE_URL=http://localhost:3001