How to Self-Host Teedy with Docker Compose

What Is Teedy?

Teedy (formerly Sismics Docs) is a lightweight, open-source document management system with OCR, full-text search, workflow routing, and 256-bit AES encryption. It handles PDFs, images, Office documents, and more. Think of it as a self-hosted alternative to simple cloud document management — not as feature-rich as Paperless-ngx for automated paperless workflows, but with built-in workflow approval and enterprise DMS features that Paperless-ngx lacks. GitHub.

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
2 GB of free disk space (plus storage for documents)
1 GB of RAM (minimum)
A domain name (optional, for remote access)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  teedy:
    image: sismics/docs:v1.11
    container_name: teedy
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      # Base URL for link generation — set to your domain
      DOCS_BASE_URL: "https://docs.example.com"
      # Initial admin email (first run only)
      DOCS_ADMIN_EMAIL_INIT: "[email protected]"
      # Initial admin password as bcrypt hash
      # This hash = "changeme" — CHANGE IT before deploying
      # Generate yours: htpasswd -bnBC 10 "" yourpassword | tr -d ':\n'
      DOCS_ADMIN_PASSWORD_INIT: "$$2a$$10$$ZgjSBaLOsHZsMvorqFo1DOKbNqiSZJpVfij5Y3iXHgFBCzXHMx6wG"
      # PostgreSQL connection
      DATABASE_URL: "jdbc:postgresql://teedy-db:5432/teedy"
      DATABASE_USER: "teedy"
      DATABASE_PASSWORD: "teedy-db-password-change-me"
      # Default language for OCR (eng = English)
      DOCS_DEFAULT_LANGUAGE: "eng"
    volumes:
      - teedy-data:/data
    depends_on:
      - teedy-db
    networks:
      - teedy-net

  teedy-db:
    image: postgres:16-alpine
    container_name: teedy-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: "teedy"
      POSTGRES_PASSWORD: "teedy-db-password-change-me"
      POSTGRES_DB: "teedy"
    volumes:
      - teedy-db:/var/lib/postgresql/data
    networks:
      - teedy-net

volumes:
  teedy-data:
  teedy-db:

networks:
  teedy-net:

Create a .env file alongside for sensitive values:

# Database password — must match in both services
DB_PASSWORD=teedy-db-password-change-me

Start the stack:

docker compose up -d

Initial Setup

Open http://your-server:8080 in a browser.
Log in with username admin and the password you set via the bcrypt hash. If you used the example hash above, the password is changeme.
Change the admin password immediately in Settings → Account.
Configure your organization name and default settings in Settings → Config.
Create tags for document organization — Teedy relies on tags as the primary organizational structure.

Configuration

Key Environment Variables

Variable	Default	Purpose
`DOCS_BASE_URL`	—	Public URL for link generation
`DOCS_DEFAULT_LANGUAGE`	`eng`	OCR language (23 supported)
`DOCS_GLOBAL_QUOTA`	—	Storage quota in bytes per user
`DOCS_BCRYPT_WORK`	`10`	Password hashing rounds (4-31)

Supported OCR Languages

Teedy uses Tesseract 4 for OCR. Supported languages include: eng (English), fra (French), deu (German), spa (Spanish), ita (Italian), por (Portuguese), rus (Russian), jpn (Japanese), kor (Korean), chi_sim (Chinese Simplified), chi_tra (Chinese Traditional), ara (Arabic), and more.

SMTP Configuration

For email notifications and document sharing:

environment:
  DOCS_SMTP_HOSTNAME: "smtp.example.com"
  DOCS_SMTP_PORT: "587"
  DOCS_SMTP_USERNAME: "[email protected]"
  DOCS_SMTP_PASSWORD: "your-smtp-password"

LDAP Authentication

Teedy supports LDAP for enterprise authentication. Configure through the web UI under Settings → LDAP.

Advanced Configuration (Optional)

Document Workflows

Teedy includes a built-in workflow system for document routing and approval:

Go to Settings → Workflow.
Create workflow steps (e.g., “Review” → “Approve” → “Archive”).
Assign reviewers to each step.
Documents move through the pipeline with notifications at each stage.

This is Teedy’s standout feature — neither Paperless-ngx nor Stirling-PDF offer workflow routing.

256-bit AES Encryption

Teedy encrypts stored documents with AES-256. This is enabled by default — all files at rest are encrypted. The encryption key is derived from the application configuration.

Webhooks

Teedy can trigger webhooks on document events (creation, update, deletion). Configure in Settings → Webhooks. Useful for integrating with automation tools like n8n or Huginn.

Two-Factor Authentication

Enable 2FA per user in Settings → Account → Security. Uses TOTP (compatible with Google Authenticator, Authy, etc.).

Reverse Proxy

Forward traffic to Teedy’s port 8080. Example with Caddy:

docs.example.com {
    reverse_proxy teedy:8080
}

See Reverse Proxy Setup for Nginx Proxy Manager and Traefik configurations.

Backup

Back up two volumes:

# Stop services
docker compose stop

# Back up document data and database
docker run --rm -v teedy-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/teedy-data-$(date +%Y%m%d).tar.gz -C /data .
docker run --rm -v teedy-db:/data -v $(pwd):/backup alpine \
  tar czf /backup/teedy-db-$(date +%Y%m%d).tar.gz -C /data .

# Restart
docker compose start

Alternatively, use pg_dump for the database:

docker exec teedy-db pg_dump -U teedy teedy > teedy-backup-$(date +%Y%m%d).sql

See Backup Strategy for automated approaches.

Troubleshooting

OCR Not Working

Symptom: Uploaded documents have no extracted text, search returns no results.

Fix: Check the DOCS_DEFAULT_LANGUAGE environment variable matches your documents’ language. Verify with:

docker exec teedy tesseract --list-langs

If your language isn’t listed, the Tesseract data package may be missing from the image.

Admin Password Not Working

Symptom: Can’t log in after first deployment.

Fix: The DOCS_ADMIN_PASSWORD_INIT must be a valid bcrypt hash with $$ (double dollar signs) escaping in docker-compose. Generate a new hash:

htpasswd -bnBC 10 "" yourpassword | tr -d ':\n'

Then double the $ signs when pasting into docker-compose. This variable only works on the first container start — after that, change the password through the web UI.

Database Connection Failed

Symptom: Teedy shows a blank page or error on startup.

Fix: Ensure DATABASE_PASSWORD matches POSTGRES_PASSWORD exactly. Check that the database container started before Teedy:

docker compose logs teedy-db

Upload Fails for Large Files

Symptom: Large document uploads fail silently.

Fix: If using a reverse proxy, increase the client body size limit. For Nginx: client_max_body_size 100m;. Teedy’s default internal limit handles files up to ~100 MB.

Resource Requirements

RAM: 512 MB minimum, 1-2 GB recommended (Java runtime + Tesseract OCR)
CPU: Low to medium — OCR processing spikes briefly during document ingestion
Disk: Application is small; storage grows with your document library

Deployment	RAM	CPU
Light use (< 1,000 docs)	512 MB - 1 GB	1 core
Medium use (1,000-10,000 docs)	1-2 GB	2 cores
Heavy use (10,000+ docs)	2-4 GB	2+ cores

Verdict

Teedy is a solid choice if you need document management with built-in workflow routing, approval chains, and enterprise features like LDAP and 2FA. It handles the “route this invoice through three approvers” use case that Paperless-ngx doesn’t address. The trade-off: development has slowed (v1.11 is from March 2023), and Teedy lacks the automated classification and machine learning tagging that makes Paperless-ngx so powerful for a paperless office workflow. If you need a traditional DMS with approval workflows, choose Teedy. If you want automated document ingestion and smart tagging, choose Paperless-ngx.

Frequently Asked Questions

How does Teedy compare to Paperless-ngx?

Teedy focuses on traditional document management with workflow routing, approval chains, and enterprise features like LDAP and encryption at rest. Paperless-ngx is better for automated document ingestion — it watches folders, classifies documents with machine learning, and auto-tags. Choose Teedy if you need approval workflows; choose Paperless-ngx if you want a paperless office with smart automation.

Is Teedy still actively maintained?

Development has slowed significantly. The latest release (v1.11) was from March 2023. The project still works well for its feature set, but don’t expect frequent updates or new features. If long-term maintenance is a priority, Paperless-ngx has a much more active development community.

Does Teedy support full-text search in scanned documents?

Yes. Teedy uses Tesseract 4 OCR to extract text from scanned PDFs and images, then indexes that text for full-text search. It supports 23 languages. Set your primary language with the DOCS_DEFAULT_LANGUAGE environment variable for best OCR accuracy.

Yes. Teedy supports multiple user accounts with role-based access control. You can share documents with specific users or groups, set read/write permissions per tag or document, and use the workflow system to route documents through approval chains with different reviewers at each step.

Does Teedy encrypt stored documents?

Yes. All documents stored in Teedy are encrypted at rest using 256-bit AES encryption by default. This is automatic — no additional configuration needed. The encryption key is derived from the application’s internal configuration.

Can I migrate documents from another DMS to Teedy?

Teedy has a REST API that supports bulk document import. You can upload documents programmatically with metadata, tags, and descriptions. There’s no built-in migration tool from specific platforms, but the API makes scripted migration straightforward. Export from your current system, then use the API to import documents with their metadata preserved.