OatmilkDevelopers

Self-hosting

Run it on your computer

Install Oatmilk on your own Mac, Linux or Windows computer, step by step, at oatmilk.localhost.

20 minutes · Beginner

This guide installs a complete Oatmilk on your own computer, for you alone, at https://oatmilk.localhost. Everything runs in Docker, and your data stays in Docker volumes on your disk.

1. Install what it needs

  • Docker. Docker Desktop on macOS and Windows; Docker Desktop or Docker Engine with the Compose plugin on Linux. Give Docker at least 4 GB of memory.
  • Bun. curl -fsSL https://bun.sh/install | bash (on Windows, inside WSL).
  • Git.

Check them:

Shell
docker compose version   # 2.20 or newer
bun --version

On Windows, run the commands in this guide in a WSL terminal, with Docker Desktop's WSL integration turned on.

2. Get Oatmilk

Shell
git clone https://github.com/AGI-Ventures-Canada/oatmilk.git
cd oatmilk
bun install

3. Run setup

Shell
bun run self-host setup

Setup asks one question at a time. Use the arrow keys and ⏎. For a personal install, answer:

QuestionAnswer
Where will Oatmilk run?On this computer
Address to open it atoatmilk.localhost (press ⏎)
Use the standard web ports, 443 and 80?Yes, unless another program uses them; then No and 8443 and 8080
Which PostgreSQL database?Run one here
Which Redis?Run one here
Where should files be kept?On this machine
How should people sign in?Accounts kept here
Who can make an account?Anyone who can open the site (only your computer can)
Which AI models should read documents and run Ask AI?See below
Should Oatmilk send email?No
Create your own account now?Yes, then your email, name and a password of 8 characters or more
Build and start Oatmilk now?Yes

AI models. Oatmilk uses AI to read statements, receipts and documents, and for Ask AI.

  • To keep everything on your computer, choose Ollama on this computer or LM Studio on this computer, and set it up with Use local AI models before you upload documents.
  • To use hosted models, choose Vercel AI Gateway and paste an AI Gateway API key.
  • None for now works too: Oatmilk keeps your books, but doesn't read documents until you add models.

Setup writes your settings to self-host/.env, builds the image and starts everything. The first build takes about 10 minutes. When it finishes, it creates your account and prints what to do next.

4. Trust the local certificate

Oatmilk serves https://oatmilk.localhost with a certificate from its own local certificate authority. Until you trust that authority, your browser warns about the certificate.

Shell
bun run self-host cert

It saves the authority to self-host/oatmilk-local-ca.crt and prints the command that trusts it on your system:

SystemCommand
macOSsudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain self-host/oatmilk-local-ca.crt
Linuxsudo cp self-host/oatmilk-local-ca.crt /usr/local/share/ca-certificates/oatmilk-local-ca.crt && sudo update-ca-certificates
Windowscertutil -addstore -f ROOT self-host\oatmilk-local-ca.crt, in an administrator PowerShell opened in the oatmilk folder

On Windows with WSL, cert prints the Linux command, which trusts the file inside WSL only: run the Windows command too, so your Windows browser trusts it. Restart your browser afterwards. Firefox keeps its own list: in Settings › Privacy & Security › Certificates › View Certificates › Authorities, import the same file.

5. Sign in and create your company

  1. Open <https://oatmilk.localhost>.
  2. Sign in with the email and password you gave setup.
  3. Create your company: its name, then its profile.

Upload a bank statement or a receipt to check that documents are read. With None for now, they wait until you add models.

6. Connect the command line (optional)

Shell
export NODE_EXTRA_CA_CERTS="$PWD/self-host/oatmilk-local-ca.crt"
npx @getoatmilk/cli login --host https://oatmilk.localhost
npx @getoatmilk/cli

See Sign in and choose a company.

Check it

Shell
bun run self-host status    # each service, and whether the site answers
bun run self-host doctor    # checks everything and says what to fix

Stop and start

Shell
bun run self-host down      # stops everything; your data stays
bun run self-host up        # starts it again

Oatmilk starts again on its own when Docker does, for example after a restart.

If something goes wrong

ProblemFix
The browser says the certificate isn't trustedRun bun run self-host cert, then the command it prints, and restart the browser
Ports 80 or 443 are takenRun setup again and answer No to the standard ports, then open https://oatmilk.localhost:8443
Another program can't open oatmilk.localhostAdd 127.0.0.1 oatmilk.localhost to /etc/hosts. Browsers and the CLI don't need it.
Setup stopped while buildingRead the output above the error, fix it, then run bun run self-host up
Your account wasn't createdbun run self-host user add --email you@example.com --first-name Ada

Update, back up and troubleshoot has more.