What is Turtl?

Turtl server is the backend that Turtl clients talk to: it covers account management (join, login and delete), data storage, syncing and permissions/sharing. Written in Node.js with PostgreSQL as its datastore, it exposes a plugin architecture so optional pieces like analytics or payment processing can be added without any particular provider being forced on you. You can run it directly (clone the repo, npm install, copy config/config.yaml.default to config/config.yaml, initialize the database with ./scripts/init-db.sh, then start node server.js) or with docker-compose, which also spawns a Postgres container and serves the API on port 8181. In Docker, any setting in config.yaml can be overridden through environment variables with a TURTL_ prefix. Uploaded files go either to the local filesystem or to an S3-compatible bucket, and email notifications are available through an SMTP plugin. The repository has no tagged releases and its last push was in March 2024; the project itself notes that running your own server is off the supported path.

Should you self-host Turtl?

Turtl scores 47/100 on selfhost.directory (how scoring works) and ranks #47 of 81 in Notes & Editors. It has 631 GitHub stars.

There was no stable release in the past 12 months, so check the repository's recent activity before you rely on it.

Setup is moderate: expect some configuration beyond a single command. It is AGPL-3.0-licensed and written mostly in JavaScript.

Its closest alternative on selfhost.directory is Memos (86/100, 64 139 stars). It scores higher overall, so compare the two before you pick. See Turtl vs Memos side by side.

Features

Account management
Client syncing
Configuration via Environment Variables
Data & Storage
Local or S3 file uploads
Login lockout after failed attempts
Plugin Architecture
Sharing and permissions

How to configure Turtl

allow_unconfirmed_invitesfalseapp.allow_unconfirmed_invites — allow sending invites to unconfirmed accounts
app.allow_unconfirmed_invites — allow sending invites to unconfirmed accounts
api_urlapp.api_url — public API URL of this server, no trailing slash
app.api_url — public API URL of this server, no trailing slash
buckets3.bucket — S3 bucket name
s3.bucket — S3 bucket name
connstrdb.connstr — Postgres connection string (config.yaml.default)
db.connstr — Postgres connection string (config.yaml.default)
enable_bookmarker_proxyfalseapp.enable_bookmarker_proxy — set to 'I UNDERSTAND THIS VIOLATES THE PRIVACY OF MY USERS' to enable; always false in production
app.enable_bookmarker_proxy — set to 'I UNDERSTAND THIS VIOLATES THE PRIVACY OF MY USERS' to enable; always false in production
enabledfalseplugins.email.enabled — enable the email plugin (config.yaml.default)
plugins.email.enabled — enable the email plugin (config.yaml.default)
endpoints3.endpoint / plugins.email.endpoint — S3 endpoint URL or SMTP endpoint
s3.endpoint / plugins.email.endpoint — S3 endpoint URL or SMTP endpoint
local/var/www/turtl/server/public/uploadsuploads.local — if set to a path, files are uploaded to the local filesystem instead of S3; otherwise set to false
uploads.local — if set to a path, files are uploaded to the local filesystem instead of S3; otherwise set to false
local_proxytrueuploads.local_proxy — proxy local file downloads through the server, avoiding CORS config
uploads.local_proxy — proxy local file downloads through the server, avoiding CORS config
lock_duration60app.login.lock_duration — user locked for this duration in seconds
app.login.lock_duration — user locked for this duration in seconds
logleveldebugLogging level (config.yaml.default)
Logging level (config.yaml.default)
max_attemps5app.login.max_attemps — max failed login attempts, -1 to disable
app.login.max_attemps — max failed login attempts, -1 to disable
max_bulk_sync_records32sync.max_bulk_sync_records — how many sync records a client can send at a time
sync.max_bulk_sync_records — how many sync records a client can send at a time
pathstylefalses3.pathstyle — use path-style S3 addressing
s3.pathstyle — use path-style S3 addressing
plugin_location/var/www/turtl/server/pluginsplugins.plugin_location — folder where plugins live (one subfolder per plugin)
plugins.plugin_location — folder where plugins live (one subfolder per plugin)
pool24db.pool — database connection pool size (config.yaml.default)
db.pool — database connection pool size (config.yaml.default)
port8181server.port — port the Turtl server listens on (config.yaml.default)
server.port — port the Turtl server listens on (config.yaml.default)
secrets3.secret — S3 secret key
s3.secret — S3 secret key
secure_hash_saltapp.secure_hash_salt — replace with a long, unique value unless running integration tests
app.secure_hash_salt — replace with a long, unique value unless running integration tests
tokens3.token — S3 access token
s3.token — S3 access token
TURTL_APP_SECURE_HASH_SALTEnv override of app.secure_hash_salt, set via env in docker-compose
Env override of app.secure_hash_salt, set via env in docker-compose
TURTL_DB_HOSTPostgres host, set via env in docker-compose (any config value can be overridden with TURTL_ + uppercase yaml path)
Postgres host, set via env in docker-compose (any config value can be overridden with TURTL_ + uppercase yaml path)
TURTL_DB_PASSWORDPostgres password, set via env in docker-compose
Postgres password, set via env in docker-compose
www_urlapp.www_url — public website URL
app.www_url — public website URL

FAQ

How do I get the server running?

The FAQ says many people hit issues with the Turtl server and recommends asking on the project's discussion board; running your own server is considered off the supported path, and the maintainers do not prioritize helping with platform-specific server problems.