How to Install CKAN Open Data Portals

CKAN (Comprehensive Knowledge Archive Network) is the most widely used open data management platform in the world. The Open Knowledge Foundation created this platform and develops it collaboratively with the global community; CKAN serves as the backbone of government data portals in various countries, such as data.gov (United States), data.gov.uk (United Kingdom), and thousands of regional agencies including Indonesia through the Satu Data program.

Technically, CKAN is a Python-based web application that provides an interface for publishing, searching, and downloading datasets. The platform is equipped with a standardized REST API, a Solr-based search engine, metadata storage in PostgreSQL, and a highly extensible plugin architecture. Organizations can add hundreds of datasets, group them into organizations, manage access rights, and visualize data directly from the browser using the built-in DataStore extension.

This tutorial covers CKAN installation using the Package Install method. This method is the easiest and most stable approach for production deployment. By the end of this tutorial, you will have an open data portal running on your own server (self-hosted). The portal includes the following components:

• CKAN application managed by Supervisor (uWSGI + DataPusher + Worker)
• NGINX as a reverse proxy facing the internet
• PostgreSQL as the main database for metadata and datasets
• Solr as the internal full-text search engine
• Redis as cache and message broker for background jobs

System Requirements

1. Hardware Specifications

CKAN is not a lightweight application as it runs several services simultaneously such as uWSGI, Solr, PostgreSQL, and Redis. Below are the recommended specifications based on the official CKAN hardware requirements guide:

Note: Sum the minimum CKAN specifications and supporting services (PostgreSQL, Solr) if installed on the same server. For better scalability, you can separate the database and Solr to different servers.

2. Operating System

The Package Install method is available for Ubuntu 22.04 LTS (Jammy Jellyfish) 64-bit.

Note: Use a fresh Ubuntu install or a server without other installed packages to ensure compatibility.

3. Required Ports

4. Software Prerequisites

Ensure the server has an active internet connection and sudo access. All other packages will be installed automatically during the installation process. The minimum required Python version is Python 3.9.

CKAN Installation Steps via Package

The installation process consists of three main components that must be performed in sequence: the CKAN package, PostgreSQL database, and Solr search engine. Do not skip steps as each component depends on the previous one.

1. Install CKAN Package

Step 1: Update Ubuntu package index:

sudo apt update
sudo apt upgrade -y

Step 2: Install OS dependencies required by CKAN (including redis-server, nginx, supervisor, and postgresql):

sudo apt install libpq5 redis-server nginx supervisor postgresql -y

Step 3: Download the CKAN package according to your Ubuntu version:

wget https://packaging.ckan.org/python-ckan_2.11-jammy_amd64.deb

Step 4: Install the CKAN package with dpkg:

sudo dpkg -i python-ckan_2.11-jammy_amd64.deb

This process installs CKAN along with its Python environment into /usr/lib/ckan/default/ and places configuration files at /etc/ckan/default/ckan.ini.

2. Configure PostgreSQL

CKAN uses PostgreSQL as its main database to store all dataset metadata, organizations, users, and resources.

Step 1: Create the CKAN database user:

sudo -u postgres createuser -S -D -R -P ckan_default

Note the password you enter as it will be used when configuring ckan.ini.

Step 2: Create the CKAN database with UTF-8 encoding:

sudo -u postgres createdb -O ckan_default ckan_default -E utf-8

Step 3: Verify the user and database creation:

sudo -u postgres psql -l

Example output:

                                 List of databases
     Name     |    Owner     | Encoding | Collate |  Ctype  |   Access privileges   
--------------+--------------+----------+---------+---------+-----------------------
 ckan_default | ckan_default | UTF8     | C.UTF-8 | C.UTF-8 | 
 postgres     | postgres     | UTF8     | C.UTF-8 | C.UTF-8 | 
 template0    | postgres     | UTF8     | C.UTF-8 | C.UTF-8 | =c/postgres          +
              |              |          |         |         | postgres=CTc/postgres
 template1    | postgres     | UTF8     | C.UTF-8 | C.UTF-8 | =c/postgres          +
              |              |          |         |         | postgres=CTc/postgres
(4 rows)

3. Install and Configure Solr

CKAN uses Apache Solr as its search engine. CKAN 2.11 requires Solr 9.x.

Step 1: Install Java (JDK):

sudo apt install default-jdk -y

Step 2: Download Solr 9.x from the official Apache Solr page:

wget https://downloads.apache.org/solr/solr/9.10.1/solr-9.10.1.tgz

Step 3: Extract the installation script:

tar xzf solr-9.10.1.tgz solr-9.10.1/bin/install_solr_service.sh --strip-components=2

Step 4: Run the installation script as root:

sudo bash ./install_solr_service.sh solr-9.10.1.tgz

Example output:

id: ‘solr’: no such user
Creating new user: solr
Adding system user `solr' (UID 115) ...
Adding new group `solr' (GID 124) ...
Adding new user `solr' (UID 115) with group `solr' ...
Creating home directory `/var/solr' ...

Extracting solr-9.10.1.tgz to /opt
Installing symlink /opt/solr -> /opt/solr-9.10.1 ...
Installing /etc/init.d/solr script ...
Installing /etc/default/solr.in.sh ...

Service solr installed.
Customize Solr startup configuration in /etc/default/solr.in.sh
● solr.service - LSB: Controls Apache Solr as a Service
     Loaded: loaded (/etc/init.d/solr; generated)
     Active: active (exited) since Tue 2026-04-07 20:59:00 WIB; 5s ago
       Docs: man:systemd-sysv-generator(8)
    Process: 6713 ExecStart=/etc/init.d/solr start (code=exited, status=0/SUCCESS)
        CPU: 27ms

Step 5: Create a new Solr core specifically for CKAN:

sudo -u solr /opt/solr/bin/solr create -c ckan

Step 6: Replace the default schema with the CKAN-specific schema:

sudo -u solr wget -O /var/solr/data/ckan/conf/managed-schema \
  https://raw.githubusercontent.com/ckan/ckan/2.11/ckan/config/solr/schema.xml

Step 7: Restart Solr:

sudo systemctl restart solr

Security Warning: Never expose port 8983 to the public internet as Solr does not have strong built-in authentication mechanisms. Use a firewall to ensure Solr is only accessible from localhost or the internal network. Update the solr_url value in ckan.ini if you use a different URL or port: solr_url = http://localhost:8983/solr/ckan.

Database and Web Server Initialization

1. Edit CKAN Configuration File

The main CKAN configuration file is located at /etc/ckan/default/ckan.ini. Open the file and ensure at least the following options are configured:

sudo nano /etc/ckan/default/ckan.ini

Find and modify the following lines:

## Site Settings
ckan.site_url = http://data.example.com

## Database Settings
sqlalchemy.url = postgresql://ckan_default:YOUR_PASSWORD@localhost/ckan_default

Replace http://data.example.com with your domain. This value is used by CKAN to build correct URLs in dataset metadata and resource links.

To allow users to upload dataset files, add FileStore configuration to ckan.ini under the [app:main] section:

ckan.uploads_enabled = true
ckan.storage_path = /var/lib/ckan/default

This configuration enables uploading CSV, JSON, PDF, and other formats directly to the server's local storage.

2. Initialize Database

After configuration is complete, run the following command to create all database tables required by CKAN:

sudo ckan db init

Example output if database initialization is successful:

Upgrading DB: SUCCESS

3. Start Web Server and Restart NGINX

All CKAN processes are managed by Supervisor. Reload Supervisor to read the latest process configuration:

sudo supervisorctl reload

Wait a few seconds, then check the status of all processes. The following three processes should show RUNNING status:

sudo supervisorctl status

Example output:

ckan-datapusher:ckan-datapusher-00   RUNNING   pid 1963, uptime 0:00:12
ckan-uwsgi:ckan-uwsgi-00             RUNNING   pid 1964, uptime 0:00:12
ckan-worker:ckan-worker-00           RUNNING   pid 1965, uptime 0:00:12

If any process shows FATAL or STOPPED status, check logs in /var/log/ckan/ for error details.

Finally, restart NGINX:

sudo service nginx restart

NGINX functions as a reverse proxy that forwards requests from port 80 to uWSGI on port 8080. The default NGINX configuration is included in the CKAN package and ready to use.

Verification and Dashboard Access

1. Access the CKAN Portal

Open a browser and access http://data.example.com. If the installation was successful, the CKAN homepage will appear similar to typical open data portals, complete with a dataset search bar, organization navigation, and a list of datasets. The portal will be empty as no data has been added yet.

2. Create a Sysadmin Account

The first administrator account must be created via command line. This mechanism is part of the security design so that no default admin account exists that could be exploited.

Activate the virtual environment:

source /usr/lib/ckan/default/bin/activate
cd /usr/lib/ckan/default/src/ckan

Run the following command and replace admin_name as needed:

ckan -c /etc/ckan/default/ckan.ini sysadmin add admin_name [email protected] name=admin_name

Continue with creating the user:

User "admin_name" not found
Create new user: admin_name? [Y/n]: y
Password : 
Repeat for confirmation: 
2026-04-10 15:02:30,902 DEBUG [ckanext.activity.logic.action] Created 'new user' activity
Successfully created user: admin_name
Added admin as sysadmin

To promote an existing user to sysadmin, use the following command:

ckan -c /etc/ckan/default/ckan.ini sysadmin add existing_username

3. Configure Basic Site Settings

After logging in as sysadmin, go to Admin > Config to configure the following parameters:

• Site Title: portal name, e.g., "XYZ City Open Data Portal"
• Site Description: brief portal description displayed in the header
• Site Logo: upload organization logo
• Homepage: front page layout options such as featured datasets or activity stream

These settings can also be configured directly via ckan.ini for more permanent control.

Example configuration:

## Site Settings
ckan.site_title = XYZ City Open Data Portal
ckan.site_description = Official open data portal of XYZ City Government
ckan.site_logo = /base/images/ckan-logo.png
ckan.favicon = /base/images/ckan.ico

After making changes to ckan.ini, restart uWSGI for the configuration to take effect:

sudo supervisorctl restart ckan-uwsgi:ckan-uwsgi-00

Additional Tips and Troubleshooting

1. HTTPS Configuration

Open the Nginx configuration file for CKAN:

sudo nano /etc/nginx/sites-available/ckan

Add listen and server_name:

proxy_temp_path /tmp/nginx_proxy 1 2;

server {
    listen 80;
    server_name data.example.com;
    client_max_body_size 100M;
    location / {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Host $host;
    }
}

Restart the nginx service:

sudo systemctl restart nginx

For production deployment, use HTTPS. One of the most practical methods is using Certbot with Let's Encrypt:

# Install Certbot and NGINX plugin
sudo apt install certbot python3-certbot-nginx -y

# Obtain and install SSL certificate
sudo certbot --non-interactive \
-m [email protected] \
--agree-tos \
--no-eff-email \
--nginx -d data.example.com \
--redirect

After SSL is active, update ckan.site_url in ckan.ini to https://data.example.com, then restart uWSGI.

2. Securing Solr from Public Access

Solr should not be accessible from the internet. Use UFW to restrict access:

# Enable UFW if not already active
sudo ufw enable

# Allow SSH, HTTP, and HTTPS
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Block access to internal ports
sudo ufw deny 8983/tcp
sudo ufw deny 5432/tcp
sudo ufw deny 6379/tcp

# Check firewall status
sudo ufw status

Solr, PostgreSQL, and Redis ports should only be accessible from localhost.

3. Viewing Logs for Debugging

All CKAN logs are stored in the /var/log/ckan/ directory. Important log files include:

• /var/log/ckan/ckan-uwsgi.stderr.log: errors and exceptions from the main application
• /var/log/ckan/ckan-datapusher.stderr.log: DataPusher process logs
• /var/log/ckan/ckan-worker.stderr.log: background job logs such as email and indexing
• /var/log/nginx/access.log: all HTTP requests to NGINX
• /var/log/nginx/error.log: NGINX errors

To monitor logs in real-time:

sudo tail -f /var/log/ckan/ckan-uwsgi.stderr.log

4. Common Issues and Solutions

Issue: PermissionError: [Errno 13] Permission denied on first access.

The i18n directory is not writable by the web server user.

Solution:

sudo chmod -R o+rx /usr/lib/ckan/default/src/ckan/ckan/public/base/i18n/

Or run:

sudo ckan -c /etc/ckan/default/ckan.ini translation js

Issue: Supervisor process shows FATAL status.

Check the related process logs:

sudo supervisorctl tail process_name stderr

Replace process_name with ckan-uwsgi, ckan-datapusher, or ckan-worker.

Issue: CKAN cannot connect to database.

Verify database connection manually:

psql -U ckan_default -h localhost -d ckan_default

Ensure the configuration in sqlalchemy.url is correct.

Issue: Dataset search not working.

Solr index needs to be rebuilt:

sudo ckan -c /etc/ckan/default/ckan.ini search-index rebuild

Issue: File upload fails.

Check FileStore configuration and storage directory permissions:

# Check ownership
ls -la /var/lib/ckan/

# Fix if needed
sudo chown -R www-data:www-data /var/lib/ckan/default
sudo chmod u+rwx /var/lib/ckan/default

5. Routine Maintenance: Database Backup

Perform regular PostgreSQL database backups using pg_dump.

# Manual backup
sudo -u postgres pg_dump ckan_default > /root/backup-ckan-$(date +%Y%m%d).sql

Add a cron job for automated backups:

echo "0 2 * * * postgres pg_dump ckan_default > /var/backups/ckan-\$(date +\%Y\%m\%d).sql" \
  | sudo tee -a /etc/cron.d/ckan-backup

6. Cleaning Database for Development

To delete all data and start fresh:

# Delete all data
sudo ckan -c /etc/ckan/default/ckan.ini db clean

# Reinitialize database
sudo ckan db init

This command deletes all data and cannot be undone.

7. Advanced Sysadmin Guide

After the portal is running, explore advanced features through official documentation:

• Organizations and Authorization: access rights and user role settings
• DataStore Extension: query data via JSON API
• Data Preview and Visualization: chart, map, and table views in browser
• CKAN API Guide: integration using REST API
• Configuration Options: complete CKAN configuration reference

Conclusion

Installing CKAN 2.11 via the Package Install method on Ubuntu provides a structured and relatively quick approach to building an open data portal. The process includes installing main dependencies like PostgreSQL and Solr, configuring ckan.ini, initializing the database, and enabling services through Supervisor and NGINX as a reverse proxy. Once the system is running, creating a sysadmin account and initial portal configuration become the final steps before use. This method is suitable for stable deployments as most components are packaged and optimized in the official CKAN package.

```