> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suji.fr/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                                                 |