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.
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.
| Piece | Where | Job |
|---|---|---|
| Reader and dashboard | client/ | Sign-in, install, reading, search |
| API and cron | server/ | Slack, encryption, backups |
| Database | MongoDB | Messages, 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.
- 1Open api.slack.com/apps and choose Create New App, then From a manifest. Pick the target workspace and paste
slack-manifest.jsonfrom the repository root. The bot is named Keeprithm, so the invite command is/invite @keeprithm. - 2The file registers this redirect URL, with no trailing slash:Redirect URL
http://localhost:3000/api/slack/callbackOn a tunnel or a real host, replace the origin and keep the path
/api/slack/callback. The origin must equalAPP_URLinclient/.env. Change it under OAuth & Permissions, and again under Sign in with Slack if that list is empty. - 3The manifest requests these Bot Token Scopes.
Bot scope Why channels:history Read messages in public channels channels:read List public channels groups:history Read messages in private channels groups:read List private channels the bot can see files:read Download files Slack still exposes to the bot users:read Resolve names, and check that the installer is the Primary Owner team:read Read the workspace identity chat:write Post the backup summary into Slack - 4The same file requests the user scopes
openid,email, andprofile. Members use these to sign in. Open Sign in with Slack and confirm the redirect URL is listed there too. - 5On 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/.envonly.
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.
- 1Create an account at cloudinary.com.
- 2On the dashboard, copy Cloud name, API Key, and API Secret.
- 3Put them in
server/.envasCLOUDINARY_CLOUD_NAME,CLOUDINARY_API_KEY, andCLOUDINARY_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.
MongoDB
Local development expects MongoDB on 127.0.0.1:27017 with no authentication, database name keeprithm. MongoDB 7 or 8 is fine.
docker run -d --name keeprithm-mongo --restart unless-stopped -p 27017:27017 mongo:8docker 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.
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" # ENCRYPTION_KEY
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" # JWT_SECRETFrom the repository root, copy the examples and then replace the empty values:
cp server/.env.example server/.env
cp client/.env.example client/.envserver/.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.
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-secret0 * * * * 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
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/authorizeSERVER_BASE_URL must include /api and must use the same port as the API. COOKIE_SECURE=false is only for http://localhost.
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.
- 1Clone the repository and move into it:Clone
git clone https://github.com/blockrithms/keeprithm.git cd keeprithm - 2Install Yarn Classic if
yarn --versionis not 1.x:Yarncorepack enable corepack prepare yarn@1.22.22 --activate - 3From the repository root:Install
yarn install - 4Start the reader and the API together, and leave the process running:Dev servers
yarn devWait until the API logs Connected to MongoDB and Listening to port 6000, and Next.js is ready on port 3000.
- 5Create 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:adminExpected 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.
http://localhost:3000/api/slack/start?flow=workspace_registerSlack 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:
/invite @YourBotNameUse 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:
- Sync the workspace. This refreshes channels and records which ones the bot has joined.
- 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_changedevent 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:
https://YOUR_PUBLIC_API_ORIGIN/api/slack-eventsSubscribe 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.
yarn migrate:encrypt:dry
yarn migrate:encryptDeploy 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.
- 1From the repository root, create the env files Compose expects: a root
.env(ports and Mongo credentials), plusserver/.env.productionandclient/.env.productionwith Slack, Cloudinary,ENCRYPTION_KEY, andJWT_SECRET. - 2Make the script executable once, then deploy:Deploy
chmod +x deploy.sh ./deploy.sh - 3Put 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 yourSERVER_BASE_URLdescribes. The dashboard is not meant to be used by browsing a raw Docker port on the open internet. - 4Set
APP_URLandFRONTEND_URLto that public HTTPS origin, with no trailing slash, and addhttps://YOUR_HOST/api/slack/callbackto both Slack redirect lists.
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 buildthenyarn start. SERVER_BASE_URLis called by the Next.js server, so it can be a private address such ashttp://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 see | What to change |
|---|---|
| Config validation error | The named variable is missing, or ENCRYPTION_KEY is not 64 hex characters. The API will not listen. |
| slack_misconfigured | SLACK_CLIENT_ID is empty in client/.env. Restart Next.js after changing it. |
| state_mismatch | The OAuth cookie was set on a different host than Slack redirected to. Open the app on APP_URL. |
| redirect_uri did not match | The 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 install | The Slack user who approved the install is not the Primary Owner. |
| A channel is still empty after backup | The bot is not in that channel, or Sync has not been run since the invite. |
| Files missing, text present | The file was over 50 MB, or Cloudinary rejected the upload. |
| Edits in Slack never show up | The events URL is not reaching POST /api/slack-events, or the signing secret does not match. |