Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs troubleshooting page #8312

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 3 additions & 42 deletions packages/twenty-website/src/content/developers/local-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ image: /images/user-guide/fields/field.png
info: Mostly for contributors or curious developers
---

Follow this guide if you would like to setup the project locally to contribute.
Follow this guide if you would like to set up the project locally to contribute.

## Prerequisites

Expand Down Expand Up @@ -225,7 +225,7 @@ Start your redis server:
</ArticleTabs>


Setup your database with the following command:
Set up your database with the following command:
```bash
npx nx database:reset twenty-server
```
Expand All @@ -246,47 +246,8 @@ Twenty's server will be up and running at [http://localhost:3000](http://localho

Twenty's frontend will be running at [http://localhost:3001](http://localhost:3001). Just log in using the seeded demo account: `[email protected]` (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 doesn't work try adding this to your vscode setting (on the dev container scope):

#### While running `npx nx start` or `npx nx start twenty-front`, Out of memory error is thrown

In `packages/twenty-front/.env` uncomment `VITE_DISABLE_TYPESCRIPT_CHECKER=true` and `VITE_DISABLE_ESLINT_CHECKER=true` to disable background checks thus reducing amount of needed RAM.

```
"editor.codeActionsOnSave": {

"source.fixAll.eslint": "explicit"

}
```
If you encounter any problem, check [Troubleshooting](https://twenty.com/developers/section/self-hosting/troubleshooting) for solutions.
BOHEUS marked this conversation as resolved.
Show resolved Hide resolved

<ArticleEditContent></ArticleEditContent>
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ The file shares are used to store uploaded images and files through the UI, and
- Terraform installed https://developer.hashicorp.com/terraform/install
- An Azure subscription with permissions to create resources

### Step by step instructions:
### Step-by-step instructions:

1. Create a new folder and copy all the files from below
2. Run `terraform init`
Expand All @@ -58,7 +58,7 @@ This uses the prebuilt images found on [docker hub](https://hub.docker.com/r/twe

- Is set in respective tf-files
- See docs [Setup Environment Variables](https://twenty.com/developers/section/self-hosting/self-hosting-var) for usage
- After deployment you could can set `IS_SIGN_UP_DISABLED=true` (and run `terraform plan/apply` again) to disable new workspaces from being created
- After deployment, you can set `IS_SIGN_UP_DISABLED=true` (and run `terraform plan/apply` again) to disable new workspaces from being created

#### Security and networking

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ This guide provides step-by-step instructions to install and configure the Twent

See docs [Setup Environment Variables](https://twenty.com/developers/section/self-hosting/self-hosting-var) for advanced configuration.


## System Requirements

- RAM: Ensure your environment has at least 2GB of RAM. Insufficient memory can cause processes to crash.
Expand Down Expand Up @@ -45,7 +44,7 @@ Follow these steps for a manual setup.

Copy the example environment file to a new .env file in your working directory:
```bash
curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/.env.example
curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/refs/tags/v0.32.0/packages/twenty-docker/.env.example
```

2. **Generate Secret Tokens**
Expand Down Expand Up @@ -77,7 +76,7 @@ Follow these steps for a manual setup.
Download the `docker-compose.yml` file to your working directory:

```bash
curl -O https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/docker-compose.yml
curl -O https://raw.githubusercontent.com/twentyhq/twenty/refs/tags/v0.32.0/packages/twenty-docker/docker-compose.yml
```

### Step 3: Launch the Application
Expand Down Expand Up @@ -169,41 +168,7 @@ By default, Twenty runs on `localhost` at port `3000`. To access it via an exter

The `SERVER_URL` must match how users access your application in their browsers.

## Troubleshooting

### Unable to Log In

If you can't log in after setup:
1. Run the following commands:
```bash
docker exec -it twenty-server-1 yarn
docker exec -it twenty-server-1 npx nx database:reset
```
2. Restart the Docker containers:
```bash
docker-compose down
docker-compose up -d
```


### Connection Issues Behind a Reverse Proxy

If you're running Twenty behind a reverse proxy and experiencing connection issues:

1. **Verify SERVER_URL:**

Ensure `SERVER_URL` in your `.env` file matches your external access URL, including `https` if SSL is enabled.

2. **Check Reverse Proxy Settings:**

- Confirm that your reverse proxy is correctly forwarding requests to the Twenty server.
- Ensure headers like `X-Forwarded-For` and `X-Forwarded-Proto` are properly set.

3. **Restart Services:**

After making changes, restart both the reverse proxy and Twenty containers.

## Persistence
#### Persistence
BOHEUS marked this conversation as resolved.
Show resolved Hide resolved

- **Data Volumes:**

Expand All @@ -213,19 +178,9 @@ If you're running Twenty behind a reverse proxy and experiencing connection issu

If deploying to a stateless environment (e.g., certain cloud services), configure external storage to persist data.

## Getting Help

If you encounter issues not covered in this guide:

- Check Logs:

View container logs for error messages:
```bash
docker-compose logs
```

- Community Support:
## Troubleshooting

Reach out to the Twenty community or support channels for assistance.
If you encounter any problem, check [Troubleshooting](https://twenty.com/developers/section/self-hosting/troubleshooting) for solutions.
BOHEUS marked this conversation as resolved.
Show resolved Hide resolved

<ArticleEditContent></ArticleEditContent>
34 changes: 34 additions & 0 deletions packages/twenty-website/src/content/developers/self-hosting/qa.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: Q&A
icon: TbCloud
image: /images/user-guide/what-is-twenty/20.png
info: You can find answers for common questions
---

## Is it possible to integrate other apps with Twenty?

It's possible to integrate Twenty with other apps using middleware like Zapier, n8n, Make, Windmill, etc.
as long as said app has API interface and webhook.

## I deleted account by accident and don't have access to workspace, what can I do?

If workspace is in cloud, contact [support]([email protected]), if workspace was in self-hosted instance:
- if there are other users in workspace, ask them to send invite link
- if the only account in workspace was deleted, then whole workspace is deleted and all data are lost

## I want to import records but error in UI appears

If file used for importing records has more than 20,000 records, then file won't be imported due to hardcoded limit.

## Can I host Twenty in this provider?

Some providers are verified by community and can be checked [here](https://twenty.com/developers/section/self-hosting/cloud-providers).
BOHEUS marked this conversation as resolved.
Show resolved Hide resolved
If provider isn't listed in linked page but gives access to console, then it's likely possible to host Twenty.

## I'd like to use Twenty at my company, but I'm missing this feature, when it'll be done?

If feature you're looking for isn't on roadmap, you can create an issue or discussion with detailed explanation of requested feature and core team will review it and come back with answer.
BOHEUS marked this conversation as resolved.
Show resolved Hide resolved

## My workspace in cloud has problems, where should I report?

Send email to [email protected] or visit [Discord server](https://discord.gg/cx5n4Jzs57) and send message for fastest response.
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
---
title: Troubleshooting
icon: TbCloud
image: /images/user-guide/what-is-twenty/20.png
---

## Troubleshooting

If you encounter any problem while setting up environment for development, upgrading your instance or self-hosting,
here are some solutions for common problems.

### Self-hosting

#### 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.
BOHEUS marked this conversation as resolved.
Show resolved Hide resolved

#### Lint on Save not working

This should work out of the box with the eslint extension installed. If this doesn't work try adding this to your vscode setting (on the dev container scope):

```
"editor.codeActionsOnSave": {

"source.fixAll.eslint": "explicit"

}
```

#### While running `npx nx start` or `npx nx start twenty-front`, Out of memory error is thrown

In `packages/twenty-front/.env` uncomment `VITE_DISABLE_TYPESCRIPT_CHECKER=true` and `VITE_DISABLE_ESLINT_CHECKER=true` to disable background checks thus reducing amount of needed RAM.

#### While running `npx nx start` there are weird [0] and [1] in logs

That's expected as command `npx nx start` is running more commands under the hood

#### While running `yarn` warnings appear in console

Warnings are informing about pulling additional dependencies which aren't explicitly stated in `package.json`, so as long as no breaking error appears, everything should work as expected.

#### When user accesses login page, error about unauthorized user trying to access workspace appears in logs

That's expected as user is unauthorized when logged out since its identity is not verified.

### 1-click Docker compose

#### Unable to Log In

If you can't log in after setup:
1. Run the following commands:
```bash
docker exec -it twenty-server-1 yarn
docker exec -it twenty-server-1 npx nx database:reset
```
BOHEUS marked this conversation as resolved.
Show resolved Hide resolved
2. Restart the Docker containers:
```bash
docker-compose down
docker-compose up -d
```

#### Connection Issues Behind a Reverse Proxy

If you're running Twenty behind a reverse proxy and experiencing connection issues:

1. **Verify SERVER_URL:**

Ensure `SERVER_URL` in your `.env` file matches your external access URL, including `https` if SSL is enabled.
Comment on lines +86 to +88
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style: Add example of correct SERVER_URL format


2. **Check Reverse Proxy Settings:**

- Confirm that your reverse proxy is correctly forwarding requests to the Twenty server.
- Ensure headers like `X-Forwarded-For` and `X-Forwarded-Proto` are properly set.
Comment on lines +92 to +93
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style: Add example nginx/apache configuration for proper header forwarding


3. **Restart Services:**

After making changes, restart both the reverse proxy and Twenty containers.

## Getting Help

If you encounter issues not covered in this guide:

- Check Logs:

View container logs for error messages:
```bash
docker-compose logs
```

- Community Support:

Reach out to the [Twenty community](https://github.com/twentyhq/twenty/issues) or [support channels](https://discord.gg/cx5n4Jzs57) for assistance.
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ image: /images/user-guide/notes/notes_header.png

## General guidelines

Always make sure to backup your database before starting the upgrade process.
Always make sure to back up your database before starting the upgrade process.

## If you used Docker Compose

Expand Down Expand Up @@ -121,7 +121,9 @@ We have updated the way we handle the Redis connection.

Update your `.env` file to use the new `REDIS_URL` variable instead of the individual Redis connection parameters.

We have also simplifed the way we handle the JWT tokens.
<ArticleEditContent></ArticleEditContent>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style: Empty ArticleEditContent tag appears to serve no purpose here and breaks the flow of the documentation.


We have also simplified the way we handle the JWT tokens.

- Removed: `ACCESS_TOKEN_SECRET`, `LOGIN_TOKEN_SECRET`, `REFRESH_TOKEN_SECRET`, `FILE_TOKEN_SECRET`
- Added: `APP_SECRET`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Start typing directly or press '/' to add elements like headings, files, or imag

### Format Content

You can format your notes right from the editor. Use markdown syntax, press the `/` key or click on the `+` icon on the editor to see the different block options, such as headings, tables, and lists. You can also attach images to your note.
You can format your notes right from the editor. Use Markdown syntax, press the `/` key or click on the `+` icon on the editor to see the different block options, such as headings, tables, and lists. You can also attach images to your note.

Highlight the text to see more formatting options like bold, italics, and alignment options.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ Here's how you can do it:

<img src="/images/user-guide/fields/deactivate-field.png" style={{width:'100%'}}/>

And, voila! You've deactivated a field. But what does this imply for your CRM operations?
And, voilà! You've deactivated a field. But what does this imply for your CRM operations?

1. **In-App Functionality:** A deactivated field will no longer be functional within the app. You won't be able to assign values to these fields anymore.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ sectionInfo: Discover how to use standard and custom objects in your workspace.

## Import data

You can import People and Companies data into Twenty from other apps using a .csv, .xslx, or .xsl file. In the <b>Companies</b> or <b>People</b> page, click on <b>Options</b> and then on <b>Import</b>.
You can import People and Companies data into Twenty from other apps using a .csv, .xlsx, or .xls file. In the <b>Companies</b> or <b>People</b> page, click on <b>Options</b> and then on <b>Import</b>.

Upload your file, match the columns, check your data and import it.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ The newly created view opens automatically.

#### From Sorting and Filtering

When you change the `Sorting` and `Filtering` of an existing view, a `Save as new view` button will appear at the right edge of the `View Bar`. This will opens the New View menu mentioned above, allowing you to create a new view out of an existing one.
When you change the `Sorting` and `Filtering` of an existing view, a `Save as new view` button will appear at the right edge of the `View Bar`. This will open the New View menu mentioned above, allowing you to create a new view out of an existing one.

<div style={{padding:'69.01% 0 0 0', position:'relative', margin: '32px 0px 0px'}}>
<iframe
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ You can customize the display of your records using views, setting different fil
A `Workspace` typically represents a company using Twenty. It holds all the records and data that you and your team members add to Twenty.
It has a single domain name, which is typically the domain name your company uses for employee email addresses.

Sure, here is the glossary in the requested markdown format:
Sure, here is the glossary in the requested Markdown format:
BOHEUS marked this conversation as resolved.
Show resolved Hide resolved

## Field
A field refers to a specific area where particular data is stored for an entity.
Expand Down
Loading