en3sis/hans repository overview

⁠🤖 Hans - Discord Bot

Hans is built with a modular architecture that makes it easy to add and remove functionality on the fly, empowering you to create a bot tailored to your community's needs.

Built with Discord.JS⁠, TypeScript⁠, Postgres 17⁠, Drizzle ORM⁠, and lots of ❤️

⁠Invite to server

Bring Hans to your Discord server and start using his available features immediately here 🔗⁠. It uses the latest hans:nightly image with the latest features.

The list of commands & plugins can be found here 🔗⁠.

⁠Developing Hans

⁠🔅 Prepare environment

yarn install
cp .env.template .env
# fill in DISCORD_TOKEN, DISCORD_CLIENT_ID, CRYPTO_KEY, CRYPTO_IV, BOT_GUILD_ID

To create your Discord application, visit the Developer Portal⁠.

Docker is required for local development — the dev script spins up a local Postgres 17 container automatically.

⁠💾 Database

Hans uses Postgres 17 with Drizzle ORM⁠. Schema is defined in TypeScript at src/db/schema.ts⁠ and migrations are auto-generated into drizzle/.

yarn db:up         # start the dev Postgres + apply migrations
yarn db:psql       # psql into the dev DB
yarn db:studio     # open Drizzle Studio at https://local.drizzle.studio
yarn db:down       # stop the dev DB (data preserved)
yarn db:reset      # wipe and recreate from scratch

When you change the schema:

# 1. Edit src/db/schema.ts
# 2. Generate a migration
yarn db:generate
# 3. Apply it locally
yarn db:migrate
# 4. Commit src/db/schema.ts and the new drizzle/ file

Production migrations are applied separately from your laptop over Tailscale — see infrastructure/README.md⁠.

⁠👩🏼‍💻 Development

⁠yarn dev

Starts the dev Postgres container (if not running), applies migrations, then launches the bot with nodemon for live-reload. Invite link prints to the console on first boot.

⁠Slash commands

All commands (under src/commands) are built with the Slash Command⁠ interaction.

Commands under the main folder are registered globally (takes a moment to propagate). Commands under bots-playground/ are guild-specific and deploy instantly — use that folder for debugging.

To redeploy commands: yarn slash:dev for dev, yarn slash for production.

⁠🧪 Tests

yarn test          # runs Jest against ./tests

Test coverage is light — contributions welcome, especially around command controllers.

⁠🏗 Production

Production runs on a single Hetzner VPS as two Docker containers (db + bot) managed by docker compose. Deploys are manual: SSH to the box and run ./infrastructure/ops/deploy.sh. Schema migrations are applied from your laptop over Tailscale.

The full production playbook — host setup, deploy flow, Tailscale configuration, backups, rollback, and the one-time data-migration procedure — lives in infrastructure/README.md⁠.

⁠Run the bot image standalone

If you just want to run the bot against your own Postgres:

docker run --env-file .env --name hans -d --restart=always \
  en3sis/hans:nightly

.env must include a DATABASE_URL reachable from the container. You are responsible for applying schema migrations against that DB before the bot connects (DATABASE_URL=... yarn db:migrate).