Trilium: Hierarchical Note-Taking

Introduction

Trilium Notes is a hierarchical note-taking application with a focus on building large personal knowledge bases. It offers a rich WYSIWYG editor, powerful note organization through tree structure, note relationships, full-text search, and advanced scripting capabilities.

Why Choose Trilium Notes?

• Hierarchical Organization: Build a tree structure for your notes with unlimited depth
• Rich Text Editing: WYSIWYG editor with markdown support
• Note Relations: Create bidirectional links and relationship maps
• Scripting: Automate tasks with JavaScript
• Encryption: Protect sensitive notes with strong encryption
• Synchronization: Sync between multiple instances
• Version History: Track changes to your notes over time
• Customization: Themes, custom CSS, and extensive configuration options

Use Cases

• Personal knowledge management
• Research organization
• Project documentation
• Daily journaling with templates
• Code snippet library
• Book notes and reading lists
• Task management and GTD systems

Prerequisites

Before you begin, ensure you have:

• Docker and Docker Compose installed on your server
• Basic understanding of Docker networking
• At least 1GB of available RAM
• 5-10GB of disk space for notes and attachments
• (Optional) Domain name for reverse proxy setup
• (Optional) SSL certificate for HTTPS access

Quick Start with Docker Compose

Basic Configuration

Create a directory for Trilium and set up the Docker Compose file:

mkdir -p ~/homelab/trilium
cd ~/homelab/trilium
nano docker-compose.yml

Here’s a basic Docker Compose configuration:

version: '3.8'

services:
  trilium:
    image: zadam/trilium:latest
    container_name: trilium
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - trilium-data:/home/node/trilium-data
    environment:
      - TRILIUM_DATA_DIR=/home/node/trilium-data
      - TZ=America/New_York
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  trilium-data:
    driver: local

Advanced Configuration with Reverse Proxy

For production use with Traefik or Nginx Proxy Manager:

version: '3.8'

services:
  trilium:
    image: zadam/trilium:latest
    container_name: trilium
    restart: unless-stopped
    networks:
      - trilium_network
      - proxy
    expose:
      - 8080
    volumes:
      - trilium-data:/home/node/trilium-data
      - trilium-backups:/home/node/backups
    environment:
      - TRILIUM_DATA_DIR=/home/node/trilium-data
      - TZ=America/New_York
      - NODE_ENV=production
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.trilium.rule=Host(`notes.yourdomain.com`)"
      - "traefik.http.routers.trilium.entrypoints=websecure"
      - "traefik.http.routers.trilium.tls=true"
      - "traefik.http.routers.trilium.tls.certresolver=letsencrypt"
      - "traefik.http.services.trilium.loadbalancer.server.port=8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

networks:
  trilium_network:
    driver: bridge
  proxy:
    external: true

volumes:
  trilium-data:
    driver: local
  trilium-backups:
    driver: local

Deploy Trilium

Start the container:

docker-compose up -d

Check the logs to ensure everything is running correctly:

docker-compose logs -f trilium

Initial Setup

First-Time Access

1. Navigate to http://YOUR-SERVER-IP:8080 in your web browser
2. You’ll be prompted to create an admin password
3. Choose a strong password - this will encrypt your data
4. Complete the initial setup wizard

Important First Steps

After logging in for the first time:

1. Configure Backup: Go to Options → Backup and set up automatic backups
2. Set Theme: Options → Appearance to choose light/dark theme
3. Configure Sync (if needed): Options → Sync for multi-device setup
4. Create Note Templates: Set up templates for recurring note types
5. Install Scripts: Browse community scripts for enhanced functionality

Data Organization

Note Types

Trilium supports various note types:

• Text Notes: Rich text with WYSIWYG editor
• Code Notes: Syntax-highlighted code with language support
• Render Notes: Custom HTML/CSS rendering
• Book Notes: Organize sub-notes as chapters
• Relation Map: Visual relationship diagrams
• Web View: Embed web content

Organizational Strategies

Create a logical structure:

Root
├── Personal
│   ├── Journal
│   ├── Health
│   └── Finance
├── Work
│   ├── Projects
│   ├── Meetings
│   └── Tasks
├── Knowledge
│   ├── Programming
│   ├── Homelab
│   └── Tutorials
└── Archive
    └── Old Projects

Using Attributes and Relations

Add metadata to notes:

• Labels: #tag, #priority=high, #status=active
• Relations: ~author=John, ~projectLink=noteId
• Template: Create note templates with #template label
• CSS: Custom styling with #cssClass=myStyle

Backup and Restore

Automated Backups

Trilium includes built-in backup functionality:

1. Go to Options → Backup
2. Enable automatic backups
3. Set backup frequency (daily recommended)
4. Configure retention policy

Manual Database Backup

Create a backup script:

#!/bin/bash
# backup-trilium.sh

BACKUP_DIR="/path/to/backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
CONTAINER_NAME="trilium"

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Stop Trilium temporarily for consistent backup
docker-compose stop trilium

# Backup data directory
docker run --rm   --volumes-from $CONTAINER_NAME   -v $BACKUP_DIR:/backup   alpine tar czf /backup/trilium_backup_$TIMESTAMP.tar.gz   /home/node/trilium-data

# Restart Trilium
docker-compose start trilium

# Keep only last 30 days of backups
find $BACKUP_DIR -name "trilium_backup_*.tar.gz" -mtime +30 -delete

echo "Backup completed: trilium_backup_$TIMESTAMP.tar.gz"

Make it executable and add to crontab:

chmod +x backup-trilium.sh
crontab -e
# Add: 0 2 * * * /path/to/backup-trilium.sh

Restore from Backup

To restore a backup:

# Stop Trilium
docker-compose down

# Extract backup
docker run --rm   -v trilium-data:/home/node/trilium-data   -v /path/to/backups:/backup   alpine tar xzf /backup/trilium_backup_TIMESTAMP.tar.gz -C /

# Restart Trilium
docker-compose up -d

Data Import and Export

Import from Other Apps

Trilium supports importing from:

• Markdown files: Drag and drop .md files
• HTML files: Import from web clippers
• OPML files: From outliner applications
• CSV: Structured data import

Export Options

Export your notes:

1. Single Note: Right-click → Export → Choose format
2. Subtree: Export entire note hierarchies
3. Full Database: Options → Advanced → Export full database
4. HTML Export: For sharing or archiving
5. Markdown Export: For portability

Bulk Import Script

Import multiple markdown files:

#!/bin/bash
# import-markdown.sh

SOURCE_DIR="/path/to/markdown/files"
TRILIUM_URL="http://localhost:8080"
TOKEN="YOUR_API_TOKEN"

for file in "$SOURCE_DIR"/*.md; do
  filename=$(basename "$file" .md)
  content=$(cat "$file")

  curl -X POST "$TRILIUM_URL/api/create-note"     -H "Authorization: $TOKEN"     -H "Content-Type: application/json"     -d "{
      "parentNoteId": "root",
      "title": "$filename",
      "type": "text",
      "content": $(echo "$content" | jq -Rs .)
    }"
done

Synchronization

Server-Server Sync

Set up sync between multiple Trilium instances:

1. On Server Instance:

   • Go to Options → Sync
   • Enable sync server
   • Note the sync URL and generate sync password

2. On Client Instance:

   • Options → Sync
   • Enter server URL and sync password
   • Click “Test Connection”
   • Enable sync

Sync Configuration

Edit the sync settings in docker-compose.yml:

environment:
  - TRILIUM_DATA_DIR=/home/node/trilium-data
  - TRILIUM_SYNC_SERVER_HOST=0.0.0.0
  - TRILIUM_SYNC_SERVER_PORT=8080

Advanced Features

Custom Scripts

Create automated workflows:

// Example: Auto-tag notes based on content
async function autoTag() {
    const notes = await api.searchForNotes('note.text*=*homelab*');
    for (const note of notes) {
        await note.setLabel('category', 'homelab');
    }
}

API Usage

Trilium provides a REST API:

# Get note content
curl -H "Authorization: YOUR_TOKEN"   http://localhost:8080/api/notes/NOTE_ID/content

# Create new note
curl -X POST http://localhost:8080/api/notes   -H "Authorization: YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{"title": "My Note", "content": "Note content"}'

Encryption

Protect sensitive notes:

1. Select note to encrypt
2. Right-click → Note actions → Protect note
3. Enter encryption password
4. Password is required to view/edit

Authentication and Security

Password Management

• Change Password: Options → Change Password
• Password Requirements: Minimum 8 characters recommended
• Password Recovery: Not possible - keep secure backup
• Protected Notes: Additional encryption layer

Security Best Practices

1. Use Strong Password: 16+ characters with complexity
2. Enable HTTPS: Always use SSL in production
3. Regular Backups: Encrypted backup storage
4. Access Control: Use reverse proxy for IP filtering
5. Update Regularly: Keep Docker image updated
6. Protected Sessions: Configure session timeout

Network Security

Restrict access with firewall rules:

# Allow only local network
sudo ufw allow from 192.168.1.0/24 to any port 8080

# Or use reverse proxy
sudo ufw deny 8080

Troubleshooting

Common Issues

Trilium won’t start

# Check logs
docker-compose logs trilium

# Common causes:
# 1. Port 8080 already in use
docker ps | grep 8080

# 2. Permission issues
sudo chown -R 1000:1000 trilium-data/

# 3. Corrupted database
# Restore from backup

Slow Performance

# Check resource usage
docker stats trilium

# Increase memory limit in docker-compose.yml
deploy:
  resources:
    limits:
      memory: 2G
    reservations:
      memory: 1G

Sync Issues

• Verify network connectivity between instances
• Check sync password is correct
• Ensure both instances are on same version
• Review sync logs in Options → Advanced → Show Sync Log

Database Corruption

# Run database integrity check
docker exec -it trilium node src/check-integrity.js

# If corrupted, restore from backup
docker-compose down
# Restore backup process (see Backup section)
docker-compose up -d

Reset Admin Password

If you forget your password:

# This will reset the database - backup first!
docker-compose down
docker volume rm trilium_trilium-data
docker-compose up -d
# You'll go through initial setup again

Enable Debug Logging

For troubleshooting:

environment:
  - DEBUG=*
  - NODE_ENV=development

Maintenance

Regular Updates

Update Trilium to the latest version:

# Pull latest image
docker-compose pull trilium

# Recreate container
docker-compose up -d trilium

# Verify version
docker exec trilium node --version

Database Optimization

Periodic maintenance:

# Vacuum database (reduces size)
docker exec -it trilium sqlite3 /home/node/trilium-data/document.db "VACUUM;"

# Check database size
docker exec trilium du -h /home/node/trilium-data/document.db

Monitoring

Monitor Trilium health:

# Check container health
docker inspect trilium | grep -A 10 Health

# Monitor logs for errors
docker-compose logs -f --tail=100 trilium

# Resource monitoring
docker stats trilium --no-stream

Tips and Best Practices

Organizational Tips

1. Use Templates: Create templates for recurring note types
2. Consistent Naming: Develop naming conventions
3. Tag Strategically: Don’t over-tag, keep it meaningful
4. Regular Reviews: Weekly review and reorganization
5. Archive Old Notes: Keep tree structure manageable

Performance Optimization

1. Image Optimization: Compress images before adding
2. Regular Vacuum: Monthly database optimization
3. Limit Tree Depth: Avoid excessive nesting
4. Archive Old Data: Move inactive notes to archive

Workflow Integration

1. Web Clipper: Use browser extension for web content
2. Mobile Access: Access via mobile browser
3. API Integration: Automate with scripts
4. Backup Automation: Set it and forget it

Additional Resources

• Official Documentation: https://github.com/zadam/trilium/wiki
• Community Forum: https://github.com/zadam/trilium/discussions
• Docker Hub: https://hub.docker.com/r/zadam/trilium
• Script Repository: Browse community scripts in the wiki
• Themes: Custom CSS themes in documentation

Conclusion

Trilium Notes is a powerful, flexible note-taking system perfect for building comprehensive personal knowledge bases. With proper setup, regular backups, and good organizational habits, it becomes an invaluable tool for managing information.

The self-hosted nature ensures your data privacy while the rich feature set provides everything needed for advanced knowledge management. Start simple, explore features gradually, and customize Trilium to fit your workflow.

Happy note-taking!