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

Migrate to a monorepo structure (#2909)

Browse Source
This commit is contained in:
Charles Bochet
2023-12-10 18:10:54 +01:00
committed by GitHub
parent a70a9281eb
commit 5bdca9de6c
2304 changed files with 37152 additions and 25869 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
packages/twenty-docs/docs/contributor/local-setup/_category_.json Normal file
View File

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

140
packages/twenty-docs/docs/contributor/local-setup/docker-setup.mdx Normal file
View File

@ -0,0 +1,140 @@
---
title: Docker Setup
sidebar_position: 3
description: Set up the project with Docker
sidebar_custom_props:
icon: TbBrandDocker
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
This guide will walk you through provisioning the project with Docker. This comes with the following advantages:
- It provides the exact same environment as the core development team.
- It includes some extra dependencies (such as `playwright`) that you might need if you wish to contribute to some advanced areas of the project.
- It provisions a PostgreSQL database.
:::info
Avoid setting up the project with Docker if you are a Windows (WSL) user, unless you have experience with it, as it will make troubleshooting harder.
If you are a Windows user, it's better to use the [yarn installation](/contributor/local-setup/yarn-setup).
:::
## Prerequisites
Make sure you have the latest [Docker](https://docs.docker.com/get-docker/) and [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) versions installed on your computer.
You can run `docker --version` to verify the installation.
## 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: Setup environment variables
You need to set some environment variables before you can work on the project. Locally, it's better to set them through `.env` files.
```bash
cd twenty
cp ./front/.env.example ./front/.env
cp ./server/.env.example ./server/.env
```
The default values should work out of the box, except for the postgres URL, which requires a small modification.
Open `./server/.env` and change to the following:
```bash
PG_DATABASE_URL=postgres://twenty:twenty@postgres:5432/default?connection_limit=1
```
## Step 3: Build
The project includes an environment containerized with Docker and orchestrated with `docker-compose`.
This installation method will also provision a PostgreSQL container.
:::info
The configuration for the build is in the `infra/dev` folder, but you can run `make` commands directly from the root folder.
:::
```bash
make build
```
## Step 4: Migrate & seed
Before running the project, you need to initialize the database by running the migrations and seed.
Start the containers:
```bash
make up
```
Setup database, run migrations, and seed:
```bash
make server-database-init
```
## Step 5: Start Twenty
Run the project with the following commands from the `root` folder:
```bash
make server-start
```
```bash
make front-start
```
You should now have:
- **Frontend** available on: [http://localhost:3001](http://localhost:3001)
- **Server** available on: [http://localhost:3000/graphql](http://localhost:3000/graphql)
- **Postgres** available on [http://localhost:5432](http://localhost:5432) and containing database named `default`
Sign in using a seeded demo account `tim@apple.dev` (password: `Applecar2025`) to start using Twenty.
### Optional
If you don't want to use the `make` command and work directly from the container, you can also ssh directly into the container:
```bash
make sh
```
Then run commands through yarn:
```bash
cd server
yarn database:init
```
### Troubleshooting
#### Docker throws errors while setting up local environment
If by any chance you run into problems with Docker, you should change the `docker-compose` to `docker compose` in `./infra/dev/Makefile` as `docker-compose` is an old version
that's becoming obsolete. (You can find more info [here](https://docs.docker.com/compose/migrate/))

54
packages/twenty-docs/docs/contributor/local-setup/ide-setup.mdx Normal file
View File

@ -0,0 +1,54 @@
---
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](/contributor/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>
### Step 4: (Docker only) Run VSCode in container
If you are using a [Docker setup](/contributor/local-setup/docker-setup), you will need to run VSCode in the container. You can do that by opening the project, clicking on the `Remote Explorer` icon on the left sidebar and then clicking on `Attach in New window` on `dev-twenty-dev` container.
<div style={{textAlign: 'center'}}>
<img src="/img/contributor/ide-start-dev-container.png" alt="Visual Studio Code: Open in container" width="90%" />
</div>
<br />
VSCode will open a new window and you will be able to use it as you would typically do. The only difference is that you will be running VSCode inside the container and you will have access to all the tools and dependencies installed in the container.
<br /><br />
If you stop your containers, you will need to restart them before opening the project in VSCode again.
## 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://twenty.com/discord).

47
packages/twenty-docs/docs/contributor/local-setup/local-setup.mdx Normal file
View File

@ -0,0 +1,47 @@
---
title: Local Setup
sidebar_position: 0
sidebar_custom_props:
icon: TbDeviceDesktop
---
import ThemedImage from '@theme/ThemedImage';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
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://twenty.com/discord) server.
## MacOS and Linux users
It's better to use [yarn installation](/contributor/local-setup/yarn-setup) as this is the easiest way to get started.
But there's also an easy way to run the project with [Docker](/contributor/local-setup/docker-setup) that you can use if you are familiar with containerized environments.
## Windows users
Windows users can install the project through WSL2. [This guide](/contributor/local-setup/yarn-setup) can help you get started.
## Project structure
The repository has the following structure:
```
twenty
└───docs // contains this documentation
└───front // contains the frontend code for the application
└───server // contains the backend code for the application
└───infra // contains docker configurations for development and production deployments
```
## 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](/contributor/local-setup/ide-setup) further in the documentation.
___

30
packages/twenty-docs/docs/contributor/local-setup/troubleshooting.mdx Normal file
View File

@ -0,0 +1,30 @@
---
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.
## Extra yarn files
If you have extra files created by yarn (`yarn.lock`, `.yarnrc.yml`, `.yarn`), you may have a yarn version issue.
Try installing [yarn classic](https://classic.yarnpkg.com/lang/en/)!
## Missing metadata schema
During Twenty installation, you need to provision your postgres database with the right schemas, extensions, and users.
This documentation includes [different ways](/contributor/local-setup/yarn-setup#step-2-set-up-postgresql-database) to set up your postgres instance.
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.

216
packages/twenty-docs/docs/contributor/local-setup/yarn-setup.mdx Normal file
View File

@ -0,0 +1,216 @@
---
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';
In this document, you'll learn how to install the project using yarn. You should use this method since it's the easiest way to get started but you can also run the project with [Docker](/contributor/local-setup/docker-setup).
:::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 v1](https://classic.yarnpkg.com/lang/en/docs/install/)
- [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md)
</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
curl -o- -L https://yarnpkg.com/install.sh | bash
```
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: Set up PostgreSQL Database
You need to have a PostgreSQL instance available to be able to use Twenty.
You need to provision this database with a `twenty` user (password: `twenty`), a `default` database and a `test` database.
<Tabs>
<TabItem value="linux" label="Linux" default>
<b>Option 1:</b> To provision your database locally:
<br /><br />
```bash
cd twenty
make provision-postgres-linux
```
<b>Option 2:</b> If you have docker installed:
<br /><br />
```bash
cd twenty
make provision-postgres-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:
<br /><br />
```bash
cd twenty
make provision-postgres-macos-intel #for intel architecture
make provision-postgres-macos-arm #for M1/M2/M3 architecture
```
<b>Option 2:</b> If you have docker installed:
<br /><br />
```bash
cd twenty
make provision-postgres-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
cd twenty
make provision-postgres-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 3: 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 ./front/.env.example ./front/.env
cp ./server/.env.example ./server/.env
```
## Step 4: Server setup
:::info
Use `nvm` to install the correct `node` version. The `server/.nvmrc` ensures all contributors use the same version.
:::
To build Twenty server and seed some data into your database, run the following commands:
```bash
cd server
nvm install #recommended
nvm use #recommended
yarn
yarn database:init
yarn start:dev
```
Twenty's server will be up and running at [http://localhost:3000/graphql](http://localhost:3000/graphql).
## Step 5: Frontend setup
:::info
For the frontend setup, too, it's better to use `nvm` to install the right node version.
:::
To set up the frontend, run the following commands in another terminal:
```bash
cd front
nvm install #recommended
nvm use #recommended
yarn
yarn start
```
Twenty's frontend will be running at [http://localhost:3001](http://localhost:3001). Just login using the seeded demo account: `tim@apple.dev` to start using Twenty.
# Troubleshouting
## Error: Failed to execute init.sql script.
```bash
cp: ./infra/dev/postgres/init.sql: No such file or directory
psql: error: /tmp/init.sql: No such file or directory
```
If you get this error it means you are not launching the local database init script from the repo's root folder. Make sure you're in `twenty/` and not in `twenty/infra/dev/scripts`.