# Teedy (sismics/docs): a self-hosted document management system with OCR and workflow

> Teedy is a Java and JavaScript document management system you run yourself, shipped as a Docker image with OCR, versioning and a REST API. It fits small teams that want metadata-driven filing without a vendor contract, and it is not a fit for anyone who needs a release cadence faster than the one the repository shows.

**sismics/docs** — Lightweight document management system packed with all the features you can expect from big expensive solutions

- Repository: https://github.com/sismics/docs
- Website: https://teedy.io
- Stars: 2,566 · Forks: 707
- Language: JavaScript
- License: GPL-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/sismics-docs

## What Teedy solves, and for whom

Teedy is a document management system you host yourself. The problem it addresses is the one that appears once a shared drive stops being enough: files that need metadata, versions, permissions, tags and a search that reads inside the file rather than only the filename. The README describes it as "an open source, lightweight document management system for individuals and businesses", and the feature list backs that up with OCR, full text search, Dublin Core metadata, custom user-defined metadata, file versioning, hierarchical groups and a workflow system.

The audience is narrow but real. A company that wants documents on its own hardware, with LDAP authentication and an audit log, does not need a hosted product with per-seat pricing. A single person with a large scanned archive gets OCR and full text search from the same image. The repository also carries a docs-android directory, so there is a mobile client, and a docs-importer for bulk loading, which matters if you are migrating rather than starting empty. The README states the system has been tested to one million documents, which is the only scale figure the project offers.

## How the pieces fit: Jetty, Hibernate and a data directory

The Dockerfile shows the architecture more clearly than the README does. The image starts from ubuntu:22.04, installs openjdk-11-jdk, then downloads Jetty 11.0.20 from Maven Central into /opt/jetty. The application is deployed as a webapp on that Jetty instance and exposes port 8080. Java options are fixed in the image as -Dfile.encoding=UTF-8 -Xmx1g, so the default heap ceiling is 1 GB unless you override it.

Persistence splits in two. Structured data goes through Hibernate to a JDBC connection, which the README describes with DATABASE_URL, DATABASE_USER, DATABASE_PASSWORD and DATABASE_POOL_SIZE. Files themselves land in /data, which the README tells you to mount as a volume. The image also installs ffmpeg, mediainfo and tesseract-ocr with language packs for Arabic, Chinese, Japanese, Korean, Russian and a dozen more, which is what makes OCR and video support work out of the box rather than as an add-on. If you supply no PostgreSQL configuration, the application falls back to an embedded H2 database; the README is explicit that this is for testing only.

## Installing Teedy with Docker Compose and PostgreSQL

The README gives a Compose example with two services: the application and a PostgreSQL 13.1 container. The application service uses the stable tag sismics/docs:v1.11, maps port 8080, and points DATABASE_URL at the database hostname. The data directory is mounted from the host at ./docs/data. Note the doubled dollar signs in DOCS_ADMIN_PASSWORD_INIT: the value must be a bcrypt hash, and each $ has to be escaped with a second one inside Compose.

```yaml
services:
  teedy-server:
    image: sismics/docs:v1.11
    restart: unless-stopped
    ports:
      - 8080:8080
    environment:
      DOCS_BASE_URL: "https://docs.example.com"
      DOCS_ADMIN_EMAIL_INIT: "admin@example.com"
      DOCS_ADMIN_PASSWORD_INIT: "$$2a$$05$$PcMNUbJvsk7QHFSfEIDaIOjk1VI9/E7IPjTKx.jkjPxkx2EOKSoPS"
      DATABASE_URL: "jdbc:postgresql://teedy-db:5432/teedy"
      DATABASE_USER: "teedy_db_user"
      DATABASE_PASSWORD: "teedy_db_password"
      DATABASE_POOL_SIZE: "10"
    volumes:
      - ./docs/data:/data
```

Bring it up with the standard command, then open http://localhost:8080 and log in as admin with the password you hashed. The README warns that the default admin password is "admin" and says to change it before production, which is worth taking literally: the initialization variables only apply on first start.

```bash
docker compose up -d
```

Before you expose the instance, set DOCS_BASE_URL to the external address. The README states that generated URLs use this value as their base, so links produced before you set it will point at the wrong host. Two other variables are worth setting early: DOCS_GLOBAL_QUOTA for the default per-user storage limit, and DOCS_DEFAULT_LANGUAGE, which accepts values such as eng, fra, deu, chi_sim or jpn and controls the default language. The README notes that DOCS_BCRYPT_WORK defaults to 10 and may be set from 4 to 31, with a warning that a high factor hits login and user creation performance.

## Where Teedy stops being the right tool

The release history is the first thing to weigh. The repository lists v1.11 from 2023-03-12, v1.10 from 2022-01-02 and v1.9 from 2021-01-25. The last push to the repository was on 2026-08-17, so work continues, but the tagged releases are years apart and the README itself labels the latest image tag on master as possibly unstable and not recommended for production. If your organisation needs a predictable upgrade path with dated security releases, that gap is a problem you cannot configure away.

The second constraint is operational. The image runs on Java 11 with a 1 GB default heap, and the README says the embedded H2 database is for testing only, so a production deployment means running PostgreSQL alongside it and backing up two things: the database and the /data volume. OCR and media conversion add CPU and memory pressure that a plain file server would not have. The third is licence scope: Teedy is GPL-2.0, which is a copyleft licence. If you plan to embed it in a product you distribute, the terms matter in a way they would not for a permissively licensed library, and that is a question for your own legal review rather than something the README settles.

## Teedy compared with Paperless-ngx and Papermerge

Paperless-ngx and Papermerge come up in the same searches, and the difference is in what the software assumes about your documents. Teedy is built around a metadata model: Dublin Core fields, custom user-defined metadata, hierarchical tags, per-user quotas, groups and a workflow system. It expects a team filing documents into a shared structure with permissions and an audit log, and it exposes a RESTful Web API and webhooks so other systems can drive it.

Paperless-ngx and Papermerge are oriented toward the scanner-to-archive path, where the job is to consume a stream of incoming paper and make it searchable. That is a narrower and often easier workflow to operate, and it is the right choice when nobody needs to assign custom metadata or run an approval step. The choice is not about which one has more features. It is about whether your problem is filing and governing documents, in which case Teedy's metadata and permission layers are the point, or ingesting and finding them, in which case the simpler model is less to maintain.

## Upgrades, the GPL-2.0 licence and what to verify first

Upgrading means changing the image tag and restarting the container. Because the application stores files under /data and everything else in the database, both have to survive the change, and the README does not document a rollback procedure or a downgrade path. Take a database dump and a copy of the data directory before you move a tag, and read the release notes for the version you are moving to, since the README covers configuration rather than migration.

The licence is GPL-2.0. For self-hosting inside your own organisation this is generally unproblematic, but if you modify Teedy and distribute it, or bundle it into something you ship, the copyleft obligations apply to the combined work. That is a decision for your legal team, not something a README can answer. The practical verification list before you commit is short: confirm your bcrypt hash and its doubled dollar signs, confirm DATABASE_URL resolves from inside the Compose network, and confirm the /data volume is on storage you actually back up. The admin password variables only take effect at initialization, so a wrong value there means recreating the admin account rather than editing a config file.

## Conclusion

Adopt Teedy if you need a self-hosted document store with OCR, Dublin Core metadata, per-user quotas and a REST API, and if you can run PostgreSQL and mount a volume at /data. Do not adopt it if you depend on frequent releases, since the newest tagged version in the repository is v1.11 from 2023-03-12, or if you want a hosted service with a support contract. Before committing, verify that the DOCS_ADMIN_PASSWORD_INIT value you generate is a bcrypt hash with every $ doubled, and confirm that your PostgreSQL connection string works against the DATABASE_URL you intend to use.

## FAQ

### What is Teedy (sismics/docs)?

It is an open source, lightweight document management system for individuals and businesses, distributed as the sismics/docs Docker image and licensed under GPL-2.0. Its features include OCR, full text search, Dublin Core metadata, file versioning, a workflow system and a RESTful Web API.

### How do I install Teedy with Docker?

Pull the stable tag sismics/docs:v1.11 and run it with port 8080 mapped and a volume mounted at /data. The README recommends the provided PostgreSQL configuration for production, since the embedded H2 database is described as testing-only.

### What is the default Teedy admin password?

The README states the default admin password is "admin" and says to change it before going to production. You can set DOCS_ADMIN_EMAIL_INIT and DOCS_ADMIN_PASSWORD_INIT at initialization instead, but the password must be a bcrypt hash with each $ escaped as $$.

### Which database does Teedy use?

It connects through Hibernate using DATABASE_URL, DATABASE_USER, DATABASE_PASSWORD and DATABASE_POOL_SIZE. If no PostgreSQL configuration is provided, it falls back to an embedded H2 database, which the README says should only be used for testing.

### Is Teedy still actively released?

The repository shows a last push on 2026-08-17, but the most recent tagged release listed is v1.11 from 2023-03-12. The README also marks the master image tag as possibly unstable and not recommended for production.

## Sources

- [License: GPL-2.0](https://github.com/sismics/docs/blob/master/LICENSE)
- [Project website](https://teedy.io)
- [README](https://github.com/sismics/docs/blob/master/README.md)
- [Releases](https://github.com/sismics/docs/releases)
- [sismics/docs on GitHub](https://github.com/sismics/docs)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sismics-docs