Sign inSign up
keepmark-api logo

keepmark/keepmark-api

By keepmark

•Updated 1 day ago

Image
0

96

keepmark/keepmark-api repository overview

Keepmark

⁠Keepmark Server

A drop-in xBrowserSync sync service: same contract, safer writes, easier to run.

Keepmark Server stores encrypted bookmark syncs for xBrowserSync and Keepmark clients. It speaks the exact xBrowserSync API v1.1.13 contract, so official xBrowserSync apps and Keepmark apps work unchanged, and adds an opt-in v1.2 contract (revisions, conflict detection, cheap change checks, sync delete, one-time encrypted handoffs).

It never sees plaintext: clients encrypt before upload, the server stores ciphertext only.

Keepmark in a browser and on Android

⁠Tags

TagNotes
1.2.1, latestCurrent release, linux/amd64 (adds one-time handoffs)
1.2.0Previous release

Pin a version tag (1.2.1) in production; latest moves with each release.

⁠Why run it

  • Nothing changes for your users. Same endpoints, same error codes, same MongoDB layout, byte-identical v1.1 responses. No user migration.
  • No silent overwrites. Every conditional write is an atomic compare-and-swap: two clients pushing on the same base get one 200 and one 409, instead of losing one sync.
  • Built to be public. Per-IP throttling with Retry-After, a daily new-sync quota, an origin allow-list, security headers, sync IDs truncated in every log line, optional deletion of unused syncs.
  • Small and auditable. One runtime dependency (MongoDB.Driver), about 2k lines of logic, 228 unit tests plus live contract scripts.

⁠Requirements

The image contains the API only. It needs MongoDB (7.x tested). Indexes are created automatically at startup.

The API connects to MongoDB at startup. If MongoDB is unreachable it logs Unable to connect to database after Db__ConnTimeout (30 s) and exits with code 1; wrong credentials fail at once with Authentication failed. With restart: unless-stopped it retries until MongoDB is ready.

⁠Quick start with Docker Compose (API + MongoDB)

  1. Create a folder and download the MongoDB init script. It creates the least-privilege database user the API connects with, on the first start only:

    mkdir keepmark && cd keepmark
    curl -fsSL --create-dirs -o mongo-init/01-create-user.sh \
      https://raw.githubusercontent.com/Keepmark/KeepmarkApi/master/mongo-init/01-create-user.sh
    chmod -R a+rX mongo-init   # the mongo container user must be able to read it
    
  2. Create .env with real passwords, then chmod 600 .env:

    MONGO_ROOT_USER=root
    MONGO_ROOT_PASSWORD=change-me-root
    XBROWSERSYNC_DB_USER=xbrowsersyncdb
    XBROWSERSYNC_DB_PWD=change-me-app
    
  3. Create docker-compose.yml:

    services:
      mongo:
        image: mongo:7.0
        restart: unless-stopped
        environment:
          MONGO_INITDB_ROOT_USERNAME: ${MONGO_ROOT_USER}
          MONGO_INITDB_ROOT_PASSWORD: ${MONGO_ROOT_PASSWORD}
          XBROWSERSYNC_DB_USER: ${XBROWSERSYNC_DB_USER}
          XBROWSERSYNC_DB_PWD: ${XBROWSERSYNC_DB_PWD}
        volumes:
          - mongo-data:/data/db
          - ./mongo-init:/docker-entrypoint-initdb.d:ro
        healthcheck:
          test: ["CMD-SHELL", "mongosh --quiet -u $$MONGO_INITDB_ROOT_USERNAME -p $$MONGO_INITDB_ROOT_PASSWORD --authenticationDatabase admin --eval 'db.adminCommand(\"ping\")'"]
          interval: 10s
          timeout: 5s
          retries: 5
          start_period: 20s
    
      api:
        image: keepmark/keepmark-api:1.2.1
        restart: unless-stopped
        depends_on:
          mongo:
            condition: service_healthy
        environment:
          Db__Host: mongo
          Db__AuthSource: admin
          XBROWSERSYNC_DB_USER: ${XBROWSERSYNC_DB_USER}
          XBROWSERSYNC_DB_PWD: ${XBROWSERSYNC_DB_PWD}
          Status__Message: "Welcome to my Keepmark service!"
        volumes:
          - api-logs:/app/logs
        ports:
          - "8080:8080"
    
    volumes:
      mongo-data:
      api-logs:
    
  4. Start and check:

    docker compose up -d
    curl http://localhost:8080/info
    

    Expected: {"location":"","maxSyncSize":1048576,"message":"Welcome to my Keepmark service!","status":1,"version":"1.2.0"}.

    Logs: docker compose logs -f api (console) and docker compose exec api cat /app/logs/api.log (rotating file).

  5. In the xBrowserSync or Keepmark app, set the service URL to your server (for public use, put it behind HTTPS; see below).

The GitHub repository⁠ has the full Compose stack with rolling MongoDB backups and hot-reloadable log level.

⁠Run with an existing MongoDB

docker run -d --name keepmark-server --restart unless-stopped -p 8080:8080 \
  -e Db__Host=your-mongo-host \
  -e XBROWSERSYNC_DB_USER=xbrowsersyncdb \
  -e XBROWSERSYNC_DB_PWD='your-db-password' \
  keepmark/keepmark-api:1.2.1

If MongoDB runs on the same host, use --network host and -e Db__Host=127.0.0.1 instead of -p 8080:8080.

The database user needs readWrite on the xbrowsersync database:

mongosh --eval "db.getSiblingDB('admin').createUser({user:'xbrowsersyncdb',pwd:'<pwd>',roles:[{role:'readWrite',db:'xbrowsersync'}]})"

⁠Upgrading

From any earlier Keepmark API image (or 1.2.0 to 1.2.1):

docker compose pull && docker compose up -d

No data migration: the existing bookmarks and newsynclogs stay as they are. 1.2.1 adds one-time handoffs; at startup it creates the handoffs collection with its expiresAt TTL index, which sweeps expired vouchers. Check that they are on (absent when Handoff__Enabled=false):

curl -s -H 'Accept-Version: 1.2.0' localhost:8080/info
# ... "capabilities":{ ..., "handoff":{"defaultTtlSeconds":600,"maxTtlSeconds":3600,...} }

/info keeps reporting "version":"1.2.0": that is the API contract version clients negotiate, not the image tag. Out-of-range Handoff__* values stop the container at startup with the reason in docker logs.

⁠Already running xBrowserSync?

Keepmark Server uses your xBrowserSync MongoDB database as it is: no data conversion, users change nothing, and going back means starting Node again. Stop the Node service, start this image against the same database (command above). Read the migration guide⁠ first: backup, settings mapping, checks and rollback.

⁠Configuration

Every setting is an environment variable. Nested keys use __ (Status__Message, Throttle__MaxRequests). Names match the xBrowserSync settings.json. Settings apply at startup: restart the container after a change.

VariableDefaultWhat it does
Db__Host / Db__Port / Db__Name127.0.0.1 / 27017 / xbrowsersyncMongoDB location
XBROWSERSYNC_DB_USER / XBROWSERSYNC_DB_PWDemptyMongoDB credentials (used when Db__Username / Db__Password are empty)
Db__AuthSourceadminDatabase that holds the user
Db__UseSrv / Db__Sslfalsemongodb+srv:// URL / TLS to MongoDB
Db__ConnTimeout30000Connection timeout, ms
Server__Port8080Listening port in the container
Server__RelativePath/Base path when served under a sub-path (e.g. /api)
Server__BehindProxyfalseTrust X-Forwarded-For; enable only behind your own proxy
Server__Https__Enabled / __CertPath / __KeyPathfalseServe HTTPS directly with a mounted PEM cert and key
Status__Onlinetruefalse = service offline, requests refused
Status__AllowNewSyncstruefalse = existing syncs work, new ones refused
Status__MessageemptyMessage shown to users in /info (markdown)
LocationemptyTwo-letter country code shown in /info
AllowedOrigins__0, __1, …empty (any)Allowed Origin values, exact strings
DailyNewSyncsLimit3New syncs per IP per UTC day, 0 = no limit
MaxSyncs5242Total syncs before new ones are refused, 0 = unlimited
MaxSyncSize1048576Max sync size in bytes (1 MB)
SyncExpiryDays0Delete syncs not read or written for N days, 0 = never
Handoff__EnabledtrueOne-time encrypted handoffs (v1.2); false hides them from /info and their routes answer 404
Handoff__DefaultTtlSeconds / Handoff__MaxTtlSeconds600 / 3600Voucher lifetime when the client sends none / the most it may ask (60–86400)
Handoff__MaxActivePerSync5Live vouchers per sync (1–100)
Handoff__MaxAttempts3Wrong codes before a code-protected voucher is deleted (1–10)
Handoff__MaxPayloadBytes4096Max encrypted voucher payload (256–65536)
Throttle__MaxRequests / Throttle__TimeWindow1000 / 300000Requests per IP per window (ms), 0 = off
Log__Stdout__Levelinfotrace, debug, info, warn, error, fatal
Log__File__Enabled / Log__File__Leveltrue / infoRotating file log (false = console only)
Log__File__Path/app/logs/api.logLog file; mount a volume on /app/logs to keep it
Log__File__RotationPeriod / Log__File__RotatedFilesToKeep1d / 5Log rotation

Logs never contain bodies, keys or full sync IDs.

⁠HTTPS

  • Reverse proxy (recommended): terminate TLS at Caddy, nginx or Traefik and set Server__BehindProxy=true so client IPs are real.
  • Direct: mount cert and key, set Server__Https__Enabled=true, Server__Https__CertPath and Server__Https__KeyPath.

⁠Image details

  • Base: mcr.microsoft.com/dotnet/aspnet:10.0, runs as the non-root app user.
  • Port: 8080.
  • Healthcheck: GET /info every 30 s.
  • Data lives in MongoDB only. Optional volume: /app/logs (file logs, writable by app out of the box).

⁠Documentation

Questions and bug reports: GitHub issues⁠.

⁠License

Copyright (C) 2026 Yari Melzani. Free software under the GNU Affero General Public License, version 3 only (AGPL-3.0-only). If you run a modified version as a network service, you must offer its source code to its users (AGPL §13). Source: https://github.com/Keepmark/KeepmarkApi⁠.

Independent implementation, compatible with the xBrowserSync protocol. Not affiliated with or endorsed by xBrowserSync.

Tag summary

Content type

Image

Digest

sha256:040ad0330…

Size

98.1 MB

Last updated

1 day ago

docker pull keepmark/keepmark-api