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:
- Navigate to:
http://localhost:8080
If on a remote server, replacelocalhost
with the server’s IP. - 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.
- 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 withsudo netstat -tuln | grep 8080
. Change the port indocker-compose.yml
(e.g.,8081:8080
) if needed. - Container fails to start:
View logs withdocker compose logs
. Common causes include incorrectNC_DB
syntax or missing volumes. - Data loss:
Ensure volumes are defined indocker-compose.yml
. Without them, data is lost when containers are removed. - Permission errors:
Verify your user is in the Docker group or usesudo
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!