> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suji.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# NocoDB

> Open-source Airtable alternative. Install, create your super-admin account, and build your first base.

[NocoDB](https://nocodb.com) is an open-source Airtable alternative. It turns a database into a smart spreadsheet with grid, gallery, kanban, and form views. You manage everything from its web UI, served at your `*.suji.fr` address.

This page covers running NocoDB on Suji end-to-end. NocoDB is maintained upstream; Suji provides the [marketplace packaging](https://github.com/suji-hq/suji-templates/tree/main/nocodb).

***

## Before you install

Nothing to prepare. NocoDB stores its data in a local database inside the install, and you'll create your admin account in the browser on first run.

<Note>
  NocoDB has no generated password and no credentials file, the **first person to sign up becomes the super-admin.** Create your account immediately after install.
</Note>

***

## Install

Dashboard → **Apps** → **NocoDB** → **Install**:

| Field      | Required | Notes                                                               |
| ---------- | -------- | ------------------------------------------------------------------- |
| VM         | yes      | Pick a VM with free capacity, or create one.                        |
| Subdomain  | no       | Suggestion is `nocodb`. Reached at `https://<subdomain>.suji.fr`.   |
| JWT secret | no       | Auto-generated if left blank. Signs auth tokens, no need to set it. |

NocoDB is lightweight (it needs only \~512 MB), so **Small** is plenty. See [Recommended size](#recommended-size).

Click **Deploy**. The install reaches `running` in \~1 minute and is live at `https://nocodb-<random>.suji.fr`, served over HTTPS through the tunnel.

***

## First connection: create your super-admin account

1. Open the install URL (`https://nocodb-<random>.suji.fr`).
2. NocoDB shows a **Sign Up** screen on first run.
3. Enter your email and a password. The first account created is the **super-admin**.
4. You land in the NocoDB dashboard.

<Warning>
  The URL is public the moment the install is `running`. Until you sign up, **anyone who reaches it can claim the super-admin account.** Do it right after deploy.
</Warning>

On later visits the URL shows **Sign In** instead.

***

## Build your first base

Inside the dashboard:

1. Click **Create Base** (NocoDB's term for a workspace/database).
2. Add tables and columns, or import from CSV/Excel.
3. Switch between **Grid**, **Gallery**, **Kanban**, and **Form** views.
4. Invite collaborators from **Team & Settings** (email features depend on an SMTP provider, not configured by default).

You can also connect NocoDB to an **external database** as a base, but the default embedded store is enough to get going.

***

## Day-to-day management

| Want to…                          | Where                                                    |
| --------------------------------- | -------------------------------------------------------- |
| Build tables / views              | The NocoDB dashboard (`https://nocodb-<random>.suji.fr`) |
| Manage users / API tokens         | Dashboard → Team & Settings                              |
| View container logs               | Dashboard → Logs (pick NocoDB)                           |
| Open a shell inside the container | Dashboard → Terminal (pick NocoDB)                       |
| Browse data on disk               | Dashboard → Files (pick the NocoDB volume)               |
| Restart the app                   | Install detail page → Restart                            |
| Upgrade to a newer version        | Install detail page → Upgrade (when available)           |
| Remove the install + its data     | Install detail page → Uninstall                          |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Everyone logged out after a restart/upgrade">
    Auth tokens are signed with the JWT secret. If it changed, existing sessions are invalidated and everyone has to sign in again, the data itself is untouched.
  </Accordion>

  <Accordion title="Invite / notification emails aren't sending">
    NocoDB needs an SMTP provider for outbound email, which isn't configured by default. Note that the network blocks outbound SMTP on ports 25 and 465. Use port 587 or an HTTP-based provider. Add the SMTP env vars to the install yourself via **Edit Install → environment variables**, then redeploy.
  </Accordion>

  <Accordion title="Bad gateway (Cloudflare 502)">
    NocoDB isn't reachable through the tunnel yet, usually still starting (wait \~30 s, especially after an upgrade). If it persists, the Logs tab shows why the container isn't up.
  </Accordion>
</AccordionGroup>

***

## Where things live

| What                               | Inside container | Named volume  |
| ---------------------------------- | ---------------- | ------------- |
| Metadata DB, attachments, app data | `/usr/app/data`  | `nocodb-data` |

NocoDB keeps its metadata in a local database in `/usr/app/data`: there's no separate database container. Uninstalling deletes the volume by default; choose **keep data** during uninstall to preserve your bases.

***

## Recommended size

* **Small is plenty.** NocoDB needs only \~512 MB and the compose caps it at 1 GB.
* Pressure scales with table size, attachments, and concurrent editors. Large bases or many users → size up.
* If you run other apps on the same VM, remember the VM's total CPU/memory is shared.

***

## Reporting issues

| Class                                                         | Where                                                                             |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| NocoDB bug (views, formulas, import, API)                     | [nocodb/nocodb issues](https://github.com/nocodb/nocodb/issues)                   |
| Marketplace packaging bug (compose / manifest / install form) | [suji-hq/suji-templates issues](https://github.com/suji-hq/suji-templates/issues) |
| Suji platform bug (dashboard, billing, network)               | Support ticket from the dashboard                                                 |