Introduce UI Components documentation (#1926)
* new contributor guide folder architecture * update content pass 1 * Prepare UI component folder to receive componentns * Add component doc example for button * Fix broken links * Fix broken links * Fix images
This commit is contained in:
Charles Bochet
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "Local setup",
|
||||
"position": 1,
|
||||
"collapsible": true,
|
||||
"collapsed": true,
|
||||
"customProps": {
|
||||
"icon": "TbDeviceDesktop"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
title: Docker Setup
|
||||
sidebar_position: 2
|
||||
sidebar_custom_props:
|
||||
icon: TbBrandDocker
|
||||
---
|
||||
|
||||
You can also provision the project with Docker. This comes with a few advantages:
|
||||
- It provides the exact same environment as our core developer team.
|
||||
- It includes some additional 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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Make sure you have the latest `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:
|
||||
|
||||
```bash
|
||||
git clone git@github.com:twentyhq/twenty.git
|
||||
```
|
||||
|
||||
## Step #2: Setup env variables
|
||||
|
||||
Twenty requires a few environment variables to be set. Locally, we recommend setting them through `.env` files.
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
We provide an environment containerized with Docker and orchestrated with `docker-compose`.
|
||||
This installation method will also provision a PostgreSQL container.
|
||||
|
||||
**Note:** The configuration for the build is stored 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
|
||||
```
|
||||
|
||||
Run database migrations, generate prisma client, and seed:
|
||||
```bash
|
||||
make server-prisma-reset
|
||||
```
|
||||
|
||||
## 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 our 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 prisma:reset
|
||||
```
|
||||
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
#### Docker throws errors while setting up local environment
|
||||
|
||||
If by any chance you will run into problems with Docker, you should change the `docker-compose` to `docker compose` in `./infra/dev/Makefile` as `docker-compose` is old version
|
||||
becoming slowly obsolete. (More info can be found [here](https://docs.docker.com/compose/migrate/))
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: IDE Setup
|
||||
sidebar_position: 4
|
||||
sidebar_custom_props:
|
||||
icon: TbBrandVscode
|
||||
---
|
||||
|
||||
This section will help you setup your IDE for the project. If you haven't setup your development environment, please refer to [Development Environment](/contributor/local-setup) section.
|
||||
|
||||
You can obviously use any IDE you want but we recommend using Visual Studio Code as our internal team uses it and we have a lot of extensions and settings that we can share with you.
|
||||
|
||||
|
||||
## Visual Studio Code
|
||||
|
||||
### 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.
|
||||
|
||||
### Open Project
|
||||
|
||||
Once you have installed 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>
|
||||
|
||||
### 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>
|
||||
|
||||
|
||||
### Docker Setup
|
||||
|
||||
If you are using a [Docker setup](/contributor/local-setup#docker-install), you will need to run VSCode in the container. You can do that by opening the project, clicking on `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 normally 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 that are installed in the container.
|
||||
|
||||
If you stop your containers, you will need to start them again before opening the project in VSCode again.
|
||||
|
||||
### Conclusion
|
||||
|
||||
You are all set to start developing the project. If you have any questions, feel free to reach out to us on [Discord](https://discord.com/invite/cx5n4Jzs57).
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
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';
|
||||
|
||||
Twenty is designed to be developer-friendly, and your local installation should be up and running in a few minutes.
|
||||
|
||||
## Discord
|
||||
|
||||
If you have any questions or need help, you can join our [Discord](https://discord.com/invite/cx5n4Jzs57) server.
|
||||
|
||||
## MacOS and Linux users
|
||||
|
||||
We recommend using [yarn installation](/contributor/local-setup/yarn-setup) as this is the easiest way to get started.
|
||||
We also provide an easy way to run the project with [Docker](/contributor/local-setup/yarn-setup) that you can use if you are familiar with containerized environments.
|
||||
|
||||
## Windows users
|
||||
|
||||
Windows users can install install the project through WSL2. We provide a [guide](/contributor/local-setup/wsl-setup) to help you get started.
|
||||
|
||||
## Project structure
|
||||
|
||||
The repository is structured as follows:
|
||||
```
|
||||
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 Twnenty 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.
|
||||
___
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
sidebar_position: 5
|
||||
sidebar_custom_props:
|
||||
icon: TbExclamationCircle
|
||||
---
|
||||
|
||||
|
||||
## Windows setup eslint prettier error: `CR` line breaks found
|
||||
|
||||
This is due to the linebreak characters of windows and the git configuration. Try running:
|
||||
```
|
||||
git config --global core.autocrlf false
|
||||
```
|
||||
|
||||
Then delete the repository and clone it again.
|
||||
|
||||
|
||||
## Yarn lock file changed and new files are created (`yarn.lock`, `.yarnrc.yml`, `.yarn`)
|
||||
|
||||
Maybe you are using yarn 3? Try installing [yarn classic](https://classic.yarnpkg.com/lang/en/)!
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Windows WSL Setup
|
||||
sidebar_position: 3
|
||||
sidebar_custom_props:
|
||||
icon: TbBrandWindows
|
||||
---
|
||||
|
||||
## Install WSL
|
||||
|
||||
Open PowerShell as Administrator and run:
|
||||
|
||||
Install WSL. Follow https://learn.microsoft.com/en-us/windows/wsl/install
|
||||
|
||||
```powershell
|
||||
wsl --install
|
||||
```
|
||||
|
||||
You should be prompted to restart your computer. If not, restart it manually.
|
||||
|
||||
Upon restart, a powershell window will open and install Ubuntu. This may take a few minutes.
|
||||
You will be prompted to create a username and password for your Ubuntu installation.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/img/contributor/wsl-complete.png" alt="Visual Studio Code: Open in container" width="90%" />
|
||||
</div>
|
||||
|
||||
## Setup your developer environment
|
||||
|
||||
### Install Git
|
||||
|
||||
Follow: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-git
|
||||
|
||||
```
|
||||
sudo apt-get install git
|
||||
```
|
||||
Then, configure your git user name and email using the following commands, replacing name and email with your own. These details will be associated with any commits that you create:
|
||||
|
||||
```
|
||||
git config --global user.name "Your Name"
|
||||
git config --global user.email "youremail@domain.com"
|
||||
```
|
||||
|
||||
**Note:$$ If you don't have a Github account, create one now with the corresponding email address. We recommend that you setup a SSH key for your Github account. Follow the instructions here: https://docs.github.com/fr/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
|
||||
|
||||
### 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 or run the following to use it now:
|
||||
|
||||
### Install Twenty project
|
||||
|
||||
You are ready to install Twenty project. Follow the [Yarn install guide](/contributor/local-setup#yarn-install-recommended) instructions.
|
||||
We don't recommend to use Docker on WSL as it adds an extra layer of complexity.
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: Yarn Setup
|
||||
sidebar_position: 1
|
||||
sidebar_custom_props:
|
||||
icon: TbScript
|
||||
---
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
|
||||
**Note:** `npm` currently does not support local packages satisfactorily. We strongly recommend using `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](https://nodejs.org/en/download)
|
||||
- [yarn](https://classic.yarnpkg.com/lang/en/docs/install/)
|
||||
|
||||
---
|
||||
|
||||
## Step #1: Git Clone
|
||||
|
||||
In your terminal, run the following command:
|
||||
|
||||
```
|
||||
git clone git@github.com:twentyhq/twenty.git
|
||||
```
|
||||
|
||||
|
||||
## Step #2: Set up PostgreSQL Database
|
||||
You need to have a PostgreSQL database available to be able to use Twenty. If you already have one available, you can skip this step.
|
||||
|
||||
If you don't, you can provision one through `docker` using the following commands:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker" default>
|
||||
|
||||
```bash
|
||||
cd twenty
|
||||
make provision-postgres
|
||||
```
|
||||
|
||||
This will create a Docker container, exposing a PostgresSQL instance at [http://localhost:5432](http://localhost:5432).
|
||||
|
||||
This instance contains two databases: `default` and `test`
|
||||
You can access them using `twenty` postgres user (password: `twenty`)
|
||||
</TabItem>
|
||||
<TabItem value="linux-wsl" label="Linux / Windows WSL">
|
||||
|
||||
To install PostgresSQL on WSL2, use the following commands:
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install postgresql postgresql-contrib
|
||||
```
|
||||
|
||||
Start postgresql service and connect to the database using default `postgres` user:
|
||||
|
||||
```bash
|
||||
sudo service postgresql start
|
||||
sudo -u postgres psql
|
||||
```
|
||||
|
||||
Create two databases:
|
||||
|
||||
```sql
|
||||
CREATE DATABASE "default";
|
||||
CREATE DATABASE "test";
|
||||
```
|
||||
|
||||
Create a user `twenty` with password `twenty`:
|
||||
|
||||
```sql
|
||||
CREATE USER twenty PASSWORD 'twenty';
|
||||
ALTER USER twenty CREATEDB;
|
||||
```
|
||||
|
||||
Create `metadata` schema:
|
||||
```sql
|
||||
CREATE SCHEMA IF NOT EXISTS "metadata";
|
||||
GRANT ALL ON SCHEMA metadata TO twenty;
|
||||
```
|
||||
|
||||
Activate `uuid-ossp` extension:
|
||||
```sql
|
||||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
## Step #3: Setup env variables
|
||||
|
||||
Twenty requires a few environment variables to be set. Locally, we recommend setting 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
|
||||
|
||||
**Note:** We recommend that you use `nvm` to install the correct `node` version. We have added a `server/.nvmrc` to ensure all contributors are using 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 prisma:reset
|
||||
yarn start:dev
|
||||
```
|
||||
|
||||
Twenty's server will be up and running at [http://localhost:3000](http://localhost:3000).
|
||||
|
||||
## Step #5: Frontend setup
|
||||
|
||||
**Note:** For the frontend setup, too, we recommend using `nvm` to install the right node version.
|
||||
To set up the frontend, run the following commands in your 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). Simply login using our seeded demo account: `tim@apple.dev` to start using Twenty.
|
||||
|
||||
Reference in New Issue
Block a user