
Deploy BigCapital | (Just Updated) Open-Source QuickBooks and Xero Alternative, Admin Login Pre-Created, Sign-up Closed
BigCapital accounting, invoicing and bookkeeping, QuickBooks alternative
cache
Just deployed
/data
bigcapital
Just deployed
gotenberg
Just deployed
database
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 thebigcapitalservice) - 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_EMAILandADMIN_PASSWORDon thebigcapitalservice (plain text) - Auth:
POST /api/auth/signinwith a JSON body ofemailandpasswordreturnsaccess_tokenandorganization_id; sendAuthorization: Bearer ACCESS_TOKENandorganization-id: ORGANIZATION_IDon every API call, and API routes answer 401 without the token - Health:
GET /api/system_dbreturns 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
