Deploy BigCapital | (Just Updated) Open-Source QuickBooks and Xero Alternative, Admin Login Pre-Created, Sign-up Closed

BigCapital accounting, invoicing and bookkeeping, QuickBooks alternative

Deploy BigCapital | (Just Updated) Open-Source QuickBooks and Xero Alternative, Admin Login Pre-Created, Sign-up Closed

Just deployed

/data

Just deployed

Just deployed

database

mariadb:11.8

Just deployed

/var/lib/mysql

Deploy and Host BigCapital on Railway

Built for an LLM agent to deploy and use. The deploy form has no fields to fill: the owner login, every secret and the database password are generated, the owner account is created before the site is reachable, and sign-up is closed to everyone else. BigCapital is open-source accounting and bookkeeping software with invoicing, bills, inventory, expenses, banking, multi-currency and financial reports, a self-hosted alternative to QuickBooks, Xero and FreshBooks.

About Hosting BigCapital

This template runs four services: bigcapital, the official BigCapital 0.25.48 server and web app images pinned by digest and joined in one thin wrapper, which owns the one public domain on port 8080 with an HTTP healthcheck at /api/system_db; database, MariaDB 11.8 with a volume at /var/lib/mysql, holding the system database and one database per company; cache, Redis with a volume at /data for the job queue and cache; and gotenberg, the PDF renderer that turns invoices and reports into PDF files.

What the wrapper fixes. Stock BigCapital ships an Envoy proxy, a separate web app image and a one-shot migration container, and leaves sign-up open: whoever reaches the sign-up page first owns the books. The wrapper runs the database migrations, starts the API with sign-up restricted to ADMIN_EMAIL, creates that owner account from ADMIN_EMAIL and ADMIN_PASSWORD, and only then opens the public port, where a small front door serves the web app and forwards /api to the server. A stranger who reaches the domain finds the account taken and registration closed. Redeploys keep the owner, the companies and every ledger entry.

Using it. Open your domain and sign in with the owner e-mail and password, then set up your organization (company name, currency, fiscal year). An agent can sign in through the API as below and send the bearer token with the organization-id header on every call. Organization setup is one call, POST /api/organization/build (company name, country, base currency, time zone, fiscal year, language), which the script below makes; until it runs, tenant routes answer 401. E-mail delivery, file attachments (they need an S3-compatible store: set S3_ENDPOINT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY on the bigcapital service) and the ClickHouse analytics sink are off.

Agent contract

  • Public URL: https://RAILWAY_PUBLIC_DOMAIN (the generated domain of the bigcapital service)
  • Private URL: http://bigcapital.railway.internal:3000 (the API itself, without the sign-up guard; the public port 8080 is the guarded front door)
  • Credentials: the variables ADMIN_EMAIL and ADMIN_PASSWORD on the bigcapital service (plain text)
  • Auth: POST /api/auth/signin with a JSON body of email and password returns access_token and organization_id; send Authorization: Bearer ACCESS_TOKEN and organization-id: ORGANIZATION_ID on every API call, and API routes answer 401 without the token
  • Health: GET /api/system_db returns 200 without credentials
#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, ADMIN_EMAIL, ADMIN_PASSWORD (variables of the bigcapital service); also curl, jq.
# optional: COUNTRY (ISO 3166 alpha-2, default US) and BASE_CURRENCY (ISO 4217, default USD) for the one-time organization setup.
R="https://$RAILWAY_PUBLIC_DOMAIN"; H="content-type: application/json"
NOPE="not-the-real-one-1"
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/api/system_db")" = 200 ]; do n=$((n+1)); [ "$n" -le 120 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/api/system_db"
# the owner exists already and sign-up is closed to everyone but that address: a stranger's sign-up is refused
curl -s -o /dev/null -w "public signup: %{http_code}\n" -H "$H" -d "$(jq -nc --arg p "$NOPE" '{firstName:"X",lastName:"Y",email:"stranger@example.com",password:$p}')" "$R/api/auth/signup"
curl -s -o /dev/null -w "wrong login: %{http_code}\n" -H "$H" -d "$(jq -nc --arg e "$ADMIN_EMAIL" --arg p "$NOPE" '{email:$e,password:$p}')" "$R/api/auth/signin"
# the generated login returns a bearer token and the organization id
LOGIN=$(curl -s -w '\n%{http_code}' -H "$H" -d "$(jq -nc --arg e "$ADMIN_EMAIL" --arg p "$ADMIN_PASSWORD" '{email:$e,password:$p}')" "$R/api/auth/signin")
echo "login: $(echo "$LOGIN" | tail -1)"
TOKEN=$(echo "$LOGIN" | sed '$d' | jq -r .access_token); ORG=$(echo "$LOGIN" | sed '$d' | jq -r .organization_id)
AUTH="authorization: Bearer $TOKEN"; OID="organization-id: $ORG"
# one-time organization setup (creates the company database); skipped when it is already built
ready() { curl -s -H "$AUTH" -H "$OID" "$R/api/organization/current" | jq -r '.is_ready // false'; }
if [ "$(ready)" != true ]; then
  curl -s -o /dev/null -w "organization build: %{http_code}\n" -H "$H" -H "$AUTH" -H "$OID" -d "$(jq -nc --arg c "${COUNTRY:-US}" --arg b "${BASE_CURRENCY:-USD}" '{name:"My Company",location:$c,baseCurrency:$b,timezone:"UTC",fiscalYear:"january",language:"en"}')" "$R/api/organization/build"
  n=0; until [ "$(ready)" = true ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
fi
echo "organization ready: $(ready)"
BODY="{\"name\":\"Agent $$\"}"
# write-auth: POST /api/item-categories needs the bearer token and organization-id; without the token, or with a wrong one, the answer is 401
curl -s -o /dev/null -w "write with key: %{http_code}\n" -H "$H" -H "$AUTH" -H "$OID" -d "$BODY" "$R/api/item-categories"
curl -s -o /dev/null -w "write without key: %{http_code}\n" -H "$H" -H "$OID" -d "$BODY" "$R/api/item-categories"
curl -s -o /dev/null -w "write wrong key: %{http_code}\n" -H "$H" -H "authorization: Bearer not-a-real-token" -H "$OID" -d "$BODY" "$R/api/item-categories"

Expected output against a fresh deploy:

health: 200
public signup: 403
wrong login: 401
login: 201
organization build: 200
organization ready: true
write with key: 201
write without key: 401
write wrong key: 401

The refusals are the contract: a request without a token is refused (write without key: 401), a stranger cannot register (public signup: 403) and a wrong password is refused (wrong login). The first start creates the databases and takes about a minute; the loop at the top waits for it, and the organization setup takes about 20 seconds.

Why Deploy BigCapital on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying BigCapital on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

  • Agent-ready - no deployer fields, a contract block, and one script that proves the app is healthy, strangers cannot register, the generated login works and the API refuses writes without a token.
  • Owner included - the owner account is created before the site is reachable, so nobody can claim your books.
  • PDF included - invoices and reports render to PDF out of the box through the bundled Gotenberg service.
  • Data survives redeploys - ledgers in MariaDB on a volume, queue and cache in Redis on a volume.
  • Pinned - BigCapital, MariaDB, Redis and Gotenberg are pinned by digest, and the wrapper by tag and digest.

Common Use Cases

  • Small-business bookkeeping and invoicing - invoices, bills, payments, customers and vendors without a QuickBooks or Xero subscription.
  • Inventory and cost tracking - items, stock adjustments and cost of goods sold alongside the ledger.
  • Multi-currency books and reports - balance sheet, profit and loss, trial balance and general ledger exports.
  • Bookkeeping driven by an AI agent - give an agent a generated login to post invoices, expenses and journal entries through the API.

Dependencies for BigCapital Hosting

  • The bigcapital service, a MariaDB service, a Redis service and a Gotenberg service, each stateful one with its volume, created by the template.

Deployment Dependencies


Template Content

More templates in this category

View Template
Rocky Linux
Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀

codestorm
51
View Template
Foundry Virtual Tabletop
Self-hosted virtual tabletop for role-playing games (license required)

Lucas
71
View Template
NEW
Double Commander in your browser
The Double Commander file manager in the cloud, from any device

Nermin Sabanovic
0