NocoDB is a powerful open-source platform that transforms any database into a smart spreadsheet interface, making data management accessible to everyone. As someone who’s set up NocoDB for various projects, I can vouch for its ease of use and versatility. In this detailed guide, I’ll share my experience to help you install NocoDB using Docker Compose on Ubuntu, ensuring a smooth and reliable setup. Whether you’re testing locally or preparing for production, this tutorial will get you up and running.

Understanding NocoDB and Docker Compose

NocoDB allows you to manage databases like PostgreSQL, MySQL, or SQLite through an intuitive web interface, eliminating the need for complex SQL queries. It’s an excellent alternative to tools like Airtable, offering both flexibility and open-source benefits. From my deployments, I’ve found NocoDB particularly useful for rapid prototyping and team collaboration.

Docker Compose is a tool that simplifies running multi-container applications by defining services in a YAML file. For NocoDB, this means you can configure the application and its database together, launching them with a single command. Ubuntu’s robust ecosystem makes it an ideal host for this containerized setup, ensuring stability and scalability.

Prerequisites for installation

Before diving in, ensure your system meets these requirements:

  • Operating system: Ubuntu 20.04 or 22.04 (this guide uses 22.04).
  • Hardware: Minimum 2GB RAM, 1 CPU core, and 20GB free disk space; 4GB RAM and 2 CPUs recommended for production.
  • Software: Docker Engine and Docker Compose plugin.
  • Access: Administrative privileges (sudo) and basic command-line knowledge.

I’ve learned that verifying these prerequisites upfront prevents most installation hiccups. If you’re unsure about your system’s specs, check them using commands like free -m for RAM or df -h for disk space.

Installing Docker on Ubuntu

Docker is essential for running NocoDB in containers. Here’s how to install it, based on the official Docker documentation and my own setup experience:

1. Update package index: 

sudo apt update

2. Install dependencies: 

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

3. Add Docker’s GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

4. Add Docker repository:

sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

5. Update packages and install Docker:

sudo apt update sudo apt install -y docker-ce

6. Verify Docker installation:

sudo docker --version

You should see output like Docker version 24.x.x.

7. Enable Docker to run at startup: 

sudo systemctl enable docker
sudo systemctl start docker

8. Add user to Docker group (to run Docker without sudo):

sudo usermod -aG docker $USER

Log out and back in to apply this change.

I’ve occasionally seen issues with outdated repositories, so using the official Docker source ensures you get the latest version.

Installing Docker Compose

Docker Compose manages NocoDB’s containers. Recent versions integrate Compose as a Docker CLI plugin, which is what we’ll install:

1. Install Docker Compose plugin: 

sudo apt install -y docker-compose-plugin

2. Verify installation: 

docker compose version

Expect output like Docker Compose version v2.x.x.

This plugin approach is simpler than the standalone binary and integrates seamlessly with Docker. If you encounter version mismatches, ensure your Docker installation is up to date.

Configuring NocoDB with Docker Compose

For simplicity, we’ll start with a SQLite-based setup, ideal for testing or small projects. SQLite is NocoDB’s default database, requiring no additional configuration.

Creating the Docker Compose file

1. Create a project directory: 

mkdir nocodb && cd nocodb

2. Create docker-compose.yml: Use a text editor like nano: 

nano docker-compose.yml

Add the following content:

version: '3.8'
services:
  nocodb:
    image: nocodb/nocodb:latest
    container_name: nocodb
    ports:
      - "8080:8080"
    volumes:
      - nocodb_data:/usr/app/data
    environment:
      - NC_AUTH_JWT_SECRET=your_jwt_secret_here
    restart: unless-stopped
volumes:
  nocodb_data:

Save and exit (Ctrl+O, Enter, Ctrl+X).

3. Generate a JWT secret:
For security, replace your_jwt_secret_here with a random string:

openssl rand -hex 32

Copy the output and update the docker-compose.yml file.

Explanation of configuration

  • image: Uses the latest NocoDB image from Docker Hub.
  • ports: Maps port 8080 on the host to the container.
  • volumes: Persists data in nocodb_data to prevent loss.
  • environment: Sets a JWT secret for secure authentication.
  • restart: Ensures the container restarts unless manually stopped.

This setup uses SQLite, which is embedded in NocoDB, making it lightweight but less suitable for heavy workloads.

Deploying NocoDB

With the configuration ready, deploy NocoDB:

1. Start the containers:

docker compose up -d

The -d flag runs containers in the background.

2. Check container status: 

docker ps

Look for a container named nocodb with status Up.

3. View logs (if needed):

docker compose logs

This helps diagnose startup issues.

In my experience, the first run may take a minute to download the image, depending on your internet speed.

Accessing and setting up NocoDB

Once running, access NocoDB via a web browser:

  1. Navigate to: http://localhost:8080 If on a remote server, replace localhost with the server’s IP.
  2. Create an admin account:
    • You’ll see a sign-up page.
    • Enter an email and a strong password.
    • Click “Sign up” to access the dashboard.
  3. Explore the dashboard:
    Create projects, connect to existing databases, or start building tables. NocoDB’s interface is intuitive, and I’ve found it quick to learn even for non-technical users.

Optional: Using PostgreSQL for production

SQLite is great for testing, but for production or larger datasets, PostgreSQL is more robust. Here’s how to modify the setup:

1. Update docker-compose.yml: Replace the previous content with:

version: '3.8'
services:
  nocodb:
    image: nocodb/nocodb:latest
    container_name: nocodb
    ports:
      - "8080:8080"
    environment:
      - NC_DB=pg://db:5432?u=nocodb&p=your_secure_password&d=nocodb
      - NC_AUTH_JWT_SECRET=your_jwt_secret_here
    depends_on:
      - db
    restart: unless-stopped
  db:
    image: postgres:13
    container_name: nocodb_postgres
    environment:
      - POSTGRES_USER=nocodb
      - POSTGRES_PASSWORD=your_secure_password
      - POSTGRES_DB=nocodb
    volumes:
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped
volumes:
  nocodb_data:
  pg_data:
  • Replace your_secure_password with a strong password.
  • Update your_jwt_secret_here as before.

2. Redeploy: 

docker compose up -d

3. Access NocoDB: Follow the same steps as above.

This setup runs two containers: one for NocoDB and one for PostgreSQL, with persistent storage for both.

Troubleshooting common issues

Here are issues I’ve encountered and their fixes:

  • Port 8080 in use:
    Check with sudo netstat -tuln | grep 8080. Change the port in docker-compose.yml (e.g., 8081:8080) if needed.
  • Container fails to start:
    View logs with docker compose logs. Common causes include incorrect NC_DB syntax or missing volumes.
  • Data loss:
    Ensure volumes are defined in docker-compose.yml. Without them, data is lost when containers are removed.
  • Permission errors:
    Verify your user is in the Docker group or use sudo for commands.

For persistent issues, the NocoDB community forum is a great resource.

Securing and maintaining NocoDB

To keep your NocoDB instance secure and reliable:

  • Use strong credentials: Ensure the JWT secret and PostgreSQL password are complex.
  • Set up a reverse proxy: For public access, use Nginx with HTTPS via Let’s Encrypt.
  • Backup volumes: 
docker compose down
tar -czvf nocodb_backup.tar.gz /var/lib/docker/volumes/nocodb_nocodb_data
  • Update NocoDB:
docker compose pull
docker compose up -d

Regular backups and updates have saved me from potential data loss in past projects.

Conclusion

Installing NocoDB with Docker Compose on Ubuntu is a straightforward way to harness a powerful data management tool. This guide covered setting up Docker, configuring NocoDB with SQLite or PostgreSQL, and securing your instance. NocoDB’s spreadsheet-like interface makes it accessible, while Docker Compose ensures a consistent deployment. Start with SQLite for testing, and scale to PostgreSQL for production needs. For further customization, explore the NocoDB documentation. Happy data managing!

You may also like

Subscribe
Notify of
guest

0 Comments
Newest
Oldest Most Voted
Inline Feedbacks
View all comments