Open Source, Self Hosted Solutions for Community Organizations

Introduction

In an era where digital tools are essential for organizing community movements, many volunteer organizations face a critical challenge: how to manage content, coordinate volunteers, and track projects without expensive proprietary software or monthly subscription fees. This is where Directus, combined with self-hosting on YunoHost, provides a powerful solution.

This tutorial will guide you through installing Directus—a free, open-source headless content management system—on a YunoHost server. By the end, you'll have a fully functional, self-hosted CMS that costs nothing beyond your existing server infrastructure.

What is Directus?

Directus is an open-source data platform that wraps your database with an intuitive admin interface and a powerful API. Unlike traditional content management systems that force you into rigid structures, Directus gives you complete control over your data model while providing a user-friendly interface for non-technical team members.

Key Features

• Open Source: Released under the GPL license, Directus is completely free to use, modify, and distribute

• Headless Architecture: Separate your content management from content presentation, enabling multi-channel publishing

• API-First Design: RESTful and GraphQL APIs built in, making integration with other tools seamless

• No Vendor Lock-In: Your data remains in your database, exportable at any time

• Customizable: Extend functionality through custom interfaces, modules, and hooks

Why Directus for Community Volunteer Movements?

Community organizations and volunteer movements have unique needs that Directus addresses exceptionally well:

1. Cost Efficiency

When self-hosted, Directus is completely free. There are no per-user fees, no premium tiers, and no feature limitations. For grassroots organizations operating on minimal budgets, this represents significant savings compared to commercial alternatives like Airtable, Contentful, or proprietary CMS platforms.

2. Data Sovereignty

Community movements often handle sensitive information—volunteer contact details, campaign strategies, or demographic data. Self-hosting ensures your data remains under your control, not on third-party servers subject to terms of service changes or data mining.

3. Flexibility for Diverse Use Cases

Directus can serve multiple functions within a single installation:

• Volunteer Database: Track volunteer skills, availability, and participation history

• Event Management: Coordinate rallies, meetings, and community actions

• Resource Library: Manage documents, images, and educational materials

• Multi-Language Content: Support communities speaking different languages

• Campaign Tracking: Monitor petition signatures, phone banking results, or canvassing data

4. Collaboration Without Barriers

The intuitive admin interface means non-technical volunteers can contribute content and manage data without developer intervention. Role-based permissions ensure appropriate access control across your organization.

5. Integration Capabilities

Through its robust API, Directus can connect with:

• Website frontends (React, Vue, WordPress)

• Mobile applications

• Automation tools like n8n or Zapier

• Communication platforms (Slack, Discord, email)

• Social media management tools

Self-Hosting: Free and Autonomous

Self-hosting means running Directus on your own server infrastructure rather than paying for cloud-hosted services. The advantages for community organizations are substantial:

Financial Benefits:

• Zero recurring subscription costs

• No per-user licensing fees

• Predictable infrastructure costs

Technical Benefits:

• Complete control over updates and maintenance schedules

• Ability to customize and extend the platform

• No artificial feature limitations

Organizational Benefits:

• Data remains in your jurisdiction

• No dependence on external service continuity

• Alignment with values of digital autonomy and open technology

Prerequisites

Before beginning this tutorial, ensure you have:

1. A YunoHost Server: YunoHost is an open-source server operating system that simplifies self-hosting. It should be installed and accessible via SSH

2. External Storage (Recommended): For this tutorial, we'll use external storage to keep application data separate from system files

3. Domain Name: A domain or subdomain pointed to your server (e.g., cms.yourorganization.org)

4. Basic Command Line Familiarity: Comfort with terminal commands and text editors

Hardware Requirements:

• Minimum: 1GB RAM, 10GB storage

• Recommended: 2GB+ RAM, 50GB+ storage (depending on media library size)

Installation Tutorial

Part 1: Preparing the Storage Environment

We'll install Directus on external storage to keep large databases and media files off the primary system drive.

Step 1: Create the application directory

sudo mkdir -p /mnt/storage/directus
cd

Note: Replace /mnt/storage with your external drive mount point if different.

Step 2: Create subdirectories for Directus data

sudo mkdir -p /mnt/storage/directus/database
sudo mkdir -p /mnt/storage/directus/uploads
sudo mkdir -p

These directories will store:

• database/: SQLite database file

• uploads/: User-uploaded media and files

• extensions/: Custom extensions and modifications

Part 2: Configuring Docker Compose

Directus runs as a Docker container, which provides isolation and easy management.

Step 3: Create the Docker Compose configuration

sudo

Step 4: Add the following configuration

version: '3'
services:
  directus:
    image: directus/directus:latest
    ports:
      - 8055:8055
    volumes:
      - /mnt/storage/directus/database:/directus/database
      - /mnt/storage/directus/uploads:/directus/uploads
      - /mnt/storage/directus/extensions:/directus/extensions
    environment:
      KEY: 'REPLACE_WITH_RANDOM_STRING_1'
      SECRET: 'REPLACE_WITH_RANDOM_STRING_2'
      ADMIN_EMAIL: 'admin@example.com'
      ADMIN_PASSWORD: 'REPLACE_WITH_STRONG_PASSWORD'
      DB_CLIENT: 'sqlite3'
      DB_FILENAME: '/directus/database/data.db'
      WEBSOCKETS_ENABLED: 'true'
      PUBLIC_URL: 'https://cms.yourorganization.org'
      RATE_LIMITER_ENABLED: 'true'
      RATE_LIMITER_POINTS: '25'
      RATE_LIMITER_DURATION: '1'
      PUBLIC_REGISTRATION: 'false'
    restart

Step 5: Generate secure authentication keys

Before proceeding, generate cryptographically secure keys:

openssl rand -base64 32
openssl rand -base64 32

The first output becomes your KEY, the second becomes your SECRET. Copy these values.

Step 6: Edit the configuration with your values

sudo

Replace the following placeholders:

• REPLACE_WITH_RANDOM_STRING_1: First generated key

• REPLACE_WITH_RANDOM_STRING_2: Second generated key

• admin@example.com: Your administrative email

• REPLACE_WITH_STRONG_PASSWORD: A strong password (12+ characters, mixed case, numbers, symbols)

• https://cms.yourorganization.org: Your actual subdomain

Save and exit the editor (Ctrl + X, then Y, then Enter).

Part 3: Setting Permissions

Docker containers run with specific user permissions. We need to ensure Directus can write to its data directories.

Step 7: Set directory ownership

sudo chown -R 1000:1000 /mnt/storage/directus/database
sudo chown -R 1000:1000 /mnt/storage/directus/uploads
sudo chown -R 1000

This grants the Docker container (running as user ID 1000) write permissions.

Part 4: Launching Directus

Step 8: Start the Directus container

sudo docker compose up -d

This command:

• Downloads the Directus Docker image (first run only)

• Creates and starts the container

• Runs it in detached mode (-d flag)

Step 9: Verify the container is running

sudo docker compose ps

You should see output showing the Directus container in "Up" status.

Step 10: Check the logs for successful startup

sudo docker compose logs --tail 20

Look for messages indicating:

• Database migrations completed

• First admin user created

• Server started at http://0.0.0.0:8055

Part 5: Configuring YunoHost Reverse Proxy

Directus is now running on port 8055, but it's only accessible locally. We need to expose it through YunoHost's web server.

Step 11: Create a subdomain in YunoHost

1. Access your YunoHost admin panel

2. Navigate to Domains → Add domain

3. Enter your subdomain: cms.yourorganization.org

4. Complete the domain installation

Step 12: Install My Webapp

1. Go to Applications → Install (+ button)

2. Search for "My Webapp"

3. Configure the installation:

   • Domain: Select cms.yourorganization.org

   • Path: / (leave as root)

   • SFTP Access: No

   • Access Control: Visitors (public)

   • Database: None

4. Complete the installation

Step 13: Configure nginx reverse proxy

YunoHost uses nginx as its web server. We need to configure it to forward requests to Directus.

sudo

Replace my_webapp__X.conf with the actual filename (the number may vary).

Step 14: Replace the file contents

Delete all existing content and replace with:

location / {
    proxy_pass http://127.0.0.1:8055;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_redirect

Save and exit.

Step 15: Test and reload nginx

sudo nginx -t

If the test is successful:

sudo

Part 6: Accessing Your Directus Installation

Step 16: Open Directus in your browser

Navigate to: https://cms.yourorganization.org

You should see the Directus login screen.

Step 17: Log in with your admin credentials

Use the email and password you set in the docker-compose.yml file.

Post-Installation: Best Practices

Security Hardening

Enable Two-Factor Authentication

1. Click your user avatar → User Directory

2. Select your admin account

3. Enable TOTP authentication

4. Use an authenticator app (Authy, Google Authenticator) to scan the QR code

Create Role-Based Access Instead of sharing the admin account:

1. Go to Settings → Roles & Permissions

2. Create roles (Editor, Contributor, Viewer)

3. Assign appropriate permissions

4. Create user accounts under Settings → User Directory

Regular Updates Keep Directus current with security patches:

cd /mnt/storage/directus
sudo docker compose pull
sudo docker compose up -d

Backup Strategy

Your YunoHost backup system should include /mnt/storage/directus. Verify this is configured:

ls

For critical data, consider additional off-site backups of the database file:

cp /mnt/storage/directus/database/data.db ~/directus-backup-$(date +%Y%m%d)

Performance Optimization

For organizations managing large datasets:

Consider PostgreSQL Instead of SQLite

SQLite is excellent for getting started, but PostgreSQL provides better performance for concurrent users. To migrate:

1. Install PostgreSQL through YunoHost

2. Update docker-compose.yml with PostgreSQL connection details

3. Use Directus's migration tools to transfer data

Monitor Resource Usage

sudo

This shows real-time resource consumption, helping you plan server capacity.

Use Case Examples for Community Organizations

Example 1: Volunteer Coordination System

Collections to Create:

• Volunteers: Name, email, phone, skills, availability, languages

• Events: Date, location, type, capacity, coordinator

• Assignments: Link volunteers to events, track attendance

• Skills: Categorize volunteer capabilities (legal aid, translation, childcare)

Workflow:

1. Volunteers register through a public form (Directus Forms feature)

2. Coordinators assign volunteers to events based on skills and availability

3. Automated emails sent through n8n integration

4. Post-event feedback collected and stored

Example 2: Multi-Language Resource Library

Collections to Create:

• Resources: Title, description, file upload, category, language

• Categories: Organizing principle (Legal Rights, Housing, Healthcare)

• Translations: Linked items for same resource in different languages

Workflow:

1. Content creators upload documents in original language

2. Translators access Directus to add translated versions

3. Public website queries Directus API based on user's language preference

4. Community members access materials without technical barriers

Example 3: Campaign Impact Tracking

Collections to Create:

• Campaigns: Name, start date, goals, status

• Actions: Type (petition, rally, letter-writing), date, participants

• Metrics: Signatures collected, attendees, volunteer hours

• Media: Photos, videos, press coverage

Workflow:

1. Campaign organizers define goals in Directus

2. Field volunteers log actions via mobile app connected to API

3. Dashboard visualizes progress toward goals

4. Reports generated for stakeholders and funders

Troubleshooting Common Issues

Container Won't Start

Symptom: docker compose ps shows status as "Restarting"

Solution:

sudo

Look for permission errors. Ensure directories have correct ownership:

sudo chown -R 1000

Cannot Access via Browser

Check 1: Verify container is running

sudo docker compose ps

Check 2: Test local connectivity

curl

Check 3: Verify nginx configuration

sudo nginx -t
cat

Forgot Admin Password

Reset via Docker:

cd /mnt/storage/directus
sudo

SSL Certificate Issues

YunoHost automatically manages Let's Encrypt certificates. If you encounter SSL errors:

sudo yunohost domain cert-install cms.yourorganization.org --force

Extending Directus for Your Organization

Custom Interfaces

Directus supports custom input interfaces. For example, create a custom volunteer availability calendar:

1. Develop the interface using Vue.js

2. Place in /mnt/storage/directus/extensions/interfaces/

3. Restart container: sudo docker compose restart

API Integration Examples

Python script to add volunteers:

import requests

DIRECTUS_URL = "https://cms.yourorganization.org"
API_TOKEN = "your-api-token"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

volunteer_data = {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "skills": ["translation", "legal_aid"]
}

response = requests.post(
    f"{DIRECTUS_URL}/items/volunteers",
    json=volunteer_data,
    headers=headers
)

print(response.json())

JavaScript for public website:

fetch('https://cms.yourorganization.org/items/events?filter[public]=true')
  .then(response => response.json())
  .then(data => {
    data.data.forEach(event => {
      console.log(`${event.title} - ${event.date}`);
    });
  });

Maintenance Schedule

Establish a regular maintenance routine:

Weekly:

• Review user activity logs

• Check disk space usage

• Verify backups completed successfully

Monthly:

• Update Directus to latest version

• Review and update user permissions

• Audit data for accuracy

Quarterly:

• Full backup test (restore to test environment)

• Security audit

• Review and optimize database performance

Conclusion

By self-hosting Directus on YunoHost, community organizations gain a powerful, free content management and data platform without the constraints of proprietary software. The combination of Directus's flexibility and YunoHost's ease of use creates an accessible self-hosting solution even for organizations with limited technical resources.

This approach embodies the principles of digital autonomy, data sovereignty, and open-source collaboration—values that align closely with many community volunteer movements. As your organization grows, Directus scales with you, supporting everything from small volunteer databases to complex multi-project coordination systems.

The initial time investment in setup pays dividends through long-term cost savings, customization possibilities, and the security of knowing your community's data remains under your control.

Additional Resources

• Directus Documentation: https://docs.directus.io

• YunoHost Documentation: https://yunohost.org/docs

• Directus Community Discord: https://discord.com/invite/directus

• YunoHost Forum: https://forum.yunohost.org

Acknowledgments

This tutorial is built on the work of countless open-source contributors to Directus, YunoHost, Docker, and the broader free software ecosystem. Their commitment to creating accessible, powerful tools makes projects like this possible for organizations working toward social change.

This tutorial is released under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0). You are free to share and adapt this content for any purpose, including commercial use, as long as you provide attribution and share modifications under the same license.