Keeprithm

Docs

Set up Keeprithm and start reading the archive.

Slack, Cloudinary, and a database you run. This is the path from an empty checkout to a workspace members can search.

The same steps live in the repository README.

Before you start

Keeprithm runs on a machine you control. There is no hosted service. The browser talks to a Next.js app, that app talks to an API you start, and the API talks to Slack, MongoDB, and your Cloudinary account.

You need these before the first backup:

  • A Slack workspace whose Primary Owner can approve the install.
  • A Cloudinary account. The free tier is enough to start. Files land in your account, not ours.
  • Local, or a host without Docker for the app: Node.js 22 and Yarn Classic 1.22. Docker is only needed if you run MongoDB in a container.
  • VPS with containers: Docker, the env files described below, then ./deploy.sh. Put nginx (or another reverse proxy) in front so the dashboard is reachable over HTTPS.
An undistributed Slack app can only be installed on the workspace where it was created. A second workspace needs its own Slack app, or Slack distribution turned on.

How it fits together

Next.js listens on port 3000 and holds the session cookies. The Express API listens on port 6000, stores the bot token, and is the only process that calls Slack and Cloudinary. MongoDB holds the archive. There is no SLACK_BOT_TOKEN in the environment. The token is created when the Primary Owner installs the workspace, then stored encrypted.

PieceWhereJob
Reader and dashboardclient/Sign-in, install, reading, search
API and cronserver/Slack, encryption, backups
DatabaseMongoDBMessages, threads, tokens

Create the Slack app

Create the app inside the workspace you want to archive. Do not use the Install App button on the Slack dashboard as a substitute for the install URL later on this page. That button never writes the bot token into MongoDB.

  1. 1
    Open api.slack.com/apps and choose Create New App, then From a manifest. Pick the target workspace and paste slack-manifest.json from the repository root. The bot is named Keeprithm, so the invite command is /invite @keeprithm.
  2. 2
    The file registers this redirect URL, with no trailing slash:
    Redirect URL
    http://localhost:3000/api/slack/callback

    On a tunnel or a real host, replace the origin and keep the path /api/slack/callback. The origin must equal APP_URL in client/.env. Change it under OAuth & Permissions, and again under Sign in with Slack if that list is empty.

  3. 3
    The manifest requests these Bot Token Scopes.
    Bot scopeWhy
    channels:historyRead messages in public channels
    channels:readList public channels
    groups:historyRead messages in private channels
    groups:readList private channels the bot can see
    files:readDownload files Slack still exposes to the bot
    users:readResolve names, and check that the installer is the Primary Owner
    team:readRead the workspace identity
    chat:writePost the backup summary into Slack
  4. 4
    The same file requests the user scopes openid, email, and profile. Members use these to sign in. Open Sign in with Slack and confirm the redirect URL is listed there too.
  5. 5
    On Basic Information, copy the Client ID, Client Secret, and Signing Secret. The Client ID goes in both env files. The secret and the signing secret go in server/.env only.

Keeprithm can read channels, files, and member names, and it can post one summary after a backup. It cannot edit or delete messages. Direct messages and group DMs are not copied.

Cloudinary

Message text lives in MongoDB. File bytes are uploaded to the Cloudinary account whose keys you put in the API env. No upload preset is required.

  1. 1
    Create an account at cloudinary.com.
  2. 2
    On the dashboard, copy Cloud name, API Key, and API Secret.
  3. 3
    Put them in server/.env as CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, and CLOUDINARY_API_SECRET.

Uploads land in the folder slack_backup. The database stores the secure URL and public id, then encrypts that metadata with the rest of the file field. Files larger than 50 MB are skipped. If an upload fails, the message text is still saved and that file is left off the message.

Cloudinary files are not covered by the message encryption. How private those URLs are depends on the access settings of your Cloudinary account.

MongoDB

Local development expects MongoDB on 127.0.0.1:27017 with no authentication, database name keeprithm. MongoDB 7 or 8 is fine.

Start MongoDB
docker run -d --name keeprithm-mongo --restart unless-stopped -p 27017:27017 mongo:8
Check it
docker exec keeprithm-mongo mongosh --quiet --eval 'db.runCommand({ ping: 1 }).ok'

The expected output is 1.

Configure

Generate two secrets before the first install. Keep ENCRYPTION_KEY forever. Message text and bot tokens written with it cannot be read with a different key, and there is no key-rotation command.

Secrets
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"  # ENCRYPTION_KEY
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"  # JWT_SECRET

From the repository root, copy the examples and then replace the empty values:

Env files
cp server/.env.example server/.env
cp client/.env.example client/.env

server/.env

Set the port, the database, both secrets, the Slack credentials, Cloudinary, and the backup schedule. Copy every SLACK_*_URL line from server/.env.example unchanged. The client id must match client/.env.

Values you change
PORT=6000
MONGODB_URL=mongodb://127.0.0.1:27017/keeprithm
FRONTEND_URL=http://localhost:3000
BACKEND_URL=http://localhost:6000

JWT_SECRET=paste-a-long-random-string
ENCRYPTION_KEY=paste-64-hex-characters

SLACK_CLIENT_ID=paste-client-id
SLACK_CLIENT_SECRET=paste-client-secret
SLACK_SIGNING_SECRET=paste-signing-secret

SLACK_BACKUP_CRON_JOB_PATTERN=0 * * * *

CLOUDINARY_CLOUD_NAME=paste-cloud-name
CLOUDINARY_API_KEY=paste-api-key
CLOUDINARY_API_SECRET=paste-api-secret

0 * * * * runs a backup at the start of every hour, in the server's local timezone. The API process has to stay up for the schedule to fire. SMTP settings are optional. They are only used for password reset and email verification.

client/.env

client/.env
NODE_ENV=development
PORT=3000
APP_URL=http://localhost:3000
SERVER_BASE_URL=http://localhost:6000/api
COOKIE_SECURE=false

SLACK_CLIENT_ID=paste-client-id
SLACK_OPENID_AUTHORIZE_URL=https://slack.com/openid/connect/authorize
SLACK_OAUTH_AUTHORIZE_URL=https://slack.com/oauth/v2/authorize

SERVER_BASE_URL must include /api and must use the same port as the API. COOKIE_SECURE=false is only for http://localhost.

A missing required server variable stops the API before it listens, with Config validation error. ENCRYPTION_KEY must be exactly 64 hex characters.

Run it locally

Use Yarn on your laptop, or on a server where you prefer not to run the app in Docker. These commands assume a Unix shell, Node 22, and MongoDB already running. For a VPS with containers, skip to Deploy on a VPS.

  1. 1
    Clone the repository and move into it:
    Clone
    git clone https://github.com/blockrithms/keeprithm.git
    cd keeprithm
  2. 2
    Install Yarn Classic if yarn --version is not 1.x:
    Yarn
    corepack enable
    corepack prepare yarn@1.22.22 --activate
  3. 3
    From the repository root:
    Install
    yarn install
  4. 4
    Start the reader and the API together, and leave the process running:
    Dev servers
    yarn dev

    Wait until the API logs Connected to MongoDB and Listening to port 6000, and Next.js is ready on port 3000.

  5. 5
    Create the operator account. The password needs at least 8 characters, with a letter and a number. This replaces any existing admin.
    Admin account
    printf 'admin@example.com\nChangeMe123\n' | yarn --cwd server seed:admin

    Expected log: Admin user created successfully! Then open localhost:3000/login and sign in with that email and password. You land on /dashboard.

The dashboard stays empty until a person finishes the Slack install in the next section.

Install a workspace

The Primary Owner of the Slack workspace opens this URL. A workspace admin is not enough. Slack checks is_primary_owner.

Install URL
http://localhost:3000/api/slack/start?flow=workspace_register

Slack shows a consent screen. After approval the browser returns to /workspace with a session cookie. If the person is not the Primary Owner, the login page says so. If you set SLACK_ALLOWED_TEAM_IDS, a workspace outside that list is refused.

In Slack, invite the bot into every channel you want kept, including private ones:

In a channel
/invite @YourBotName

Use the name you gave the Slack app. A channel is invisible to the archive until the bot is a member.

Back on the dashboard, as the operator:

  1. Sync the workspace. This refreshes channels and records which ones the bot has joined.
  2. Backup the workspace. This pulls history and thread replies for those channels, and uploads files up to 50 MB.

One backup or sync runs at a time. A second click returns HTTP 409 until the job finishes. The hourly cron calls the same backup. The first run can only copy history Slack is still willing to send, which on the free plan is about the last 90 days.

Use the archive

Operator

The email account you seeded is the operator. /dashboard shows archive counts, how fresh each workspace backup is, channel sync, a manual backup, and the option to block a user. The size figure is MongoDB storage for messages and threads. It does not include Cloudinary bytes.

Workspace members

Other people use Sign in with Slack on /login. That starts /api/slack/start?flow=signin. The public register page is disabled. After sign-in they open /workspace and see only archived channels they belong to, including private ones the bot is in.

Open a channel to read messages, threads, reactions, and files the way they were sent. Search needs at least 3 characters. Ctrl+K (Cmd+K on a Mac) focuses search. A result opens the message in its channel. Search matches word prefixes. It is not Slack's search syntax, and it does not stem words.

What is kept

  • Messages, thread replies, reactions, mentions, and files up to 50 MB.
  • Edits, once Slack can deliver a message_changed event to your API.
  • Each later backup only fetches messages newer than the last saved timestamp on that channel.

Deletes in Slack are left as they were in the archive. Direct messages are not copied.

Live edits

Scheduled backups and the dashboard button work on localhost. Live edits need Slack to reach your API over HTTPS. slack-manifest.json leaves this out, because Slack rejects event subscriptions until that address is public.

In the Slack app, open Event Subscriptions. Set the request URL to:

Events URL
https://YOUR_PUBLIC_API_ORIGIN/api/slack-events

Subscribe to the message bot event for public and private channels. The signing secret must be the one in server/.env. The handler answers Slack's URL check and applies message_changed onto a message that is already stored. A history backup does not re-fetch a message it already saved.

Encryption

Message and reply bodies, sender names, mentions, reactions, file metadata, and bot tokens are stored with AES-256-GCM. The master key is ENCRYPTION_KEY. A second key derived from it builds the search index, so search still works. Passwords stay bcrypt. User names, emails, and channel names are stored in plaintext.

If a database already has rows from before encryption, dry-run the migration first. It writes nothing. Run the real pass with the production key while a backup is not writing. It is safe to run again.

Encrypt existing rows
yarn migrate:encrypt:dry
yarn migrate:encrypt

Deploy on a VPS

Docker with deploy.sh

On a VPS, the supported container path is ./deploy.sh. It runs docker compose --env-file ./.env up --build -d, starts the API, the reader, and MongoDB in the background, then prunes unused Docker resources.

  1. 1
    From the repository root, create the env files Compose expects: a root .env (ports and Mongo credentials), plus server/.env.production and client/.env.production with Slack, Cloudinary, ENCRYPTION_KEY, and JWT_SECRET.
  2. 2
    Make the script executable once, then deploy:
    Deploy
    chmod +x deploy.sh
    ./deploy.sh
  3. 3
    Put nginx (or Caddy, Traefik, etc.) in front with TLS. Proxy the public origin to the published reader port from CLIENT_PORT, and keep the API reachable the way your SERVER_BASE_URL describes. The dashboard is not meant to be used by browsing a raw Docker port on the open internet.
  4. 4
    Set APP_URL and FRONTEND_URL to that public HTTPS origin, with no trailing slash, and add https://YOUR_HOST/api/slack/callback to both Slack redirect lists.
MongoDB in Compose should stay on the private Docker network. Do not publish the database port to the public internet.

Yarn without Docker for the app

If you prefer to run the processes on the host yourself, use Yarn. Optionally keep them alive with pm2 (or systemd).

  • API: from server/, NODE_ENV=production yarn start.
  • Web: from client/, yarn build then yarn start.
  • SERVER_BASE_URL is called by the Next.js server, so it can be a private address such as http://127.0.0.1:6000/api.
  • Put TLS and the public hostname on a reverse proxy in front of the reader, same as above.
  • MongoDB should require authentication and should not be published to the internet.

Troubleshooting

What you seeWhat to change
Config validation errorThe named variable is missing, or ENCRYPTION_KEY is not 64 hex characters. The API will not listen.
slack_misconfiguredSLACK_CLIENT_ID is empty in client/.env. Restart Next.js after changing it.
state_mismatchThe OAuth cookie was set on a different host than Slack redirected to. Open the app on APP_URL.
redirect_uri did not matchThe Slack redirect URL must equal APP_URL plus /api/slack/callback, with no trailing slash, on both the OAuth page and the OpenID page.
Only the Primary Workspace Owner can installThe Slack user who approved the install is not the Primary Owner.
A channel is still empty after backupThe bot is not in that channel, or Sync has not been run since the invite.
Files missing, text presentThe file was over 50 MB, or Cloudinary rejected the upload.
Edits in Slack never show upThe events URL is not reaching POST /api/slack-events, or the signing secret does not match.