# Invoicing

> Deploy the open-source alternative to FreshBooks, step by step, by hand or with a coding agent.

Invoicing is an open-source alternative to FreshBooks. You keep a list of clients, create invoices with line items, taxes and discounts, and email them with a PDF attached and a link to an online copy. It records payments, sends reminders before and after the due date, creates recurring invoices, and can add a Stripe "Pay" button so clients pay by card.

It runs as one Docker image plus a Postgres database. The source is in `apps/invoicing` of https://github.com/gtalarico/saas-clones.

## Required vs optional

A working deploy needs only the first three rows. Everything else can be added later, one piece at a time, without redeploying from scratch: set the variables, restart, and check.

| Feature | Required? | What happens without it | How to add it later |
|---------|-----------|-------------------------|---------------------|
| Postgres (`DATABASE_URL`) | Required | The app won't start | Part of every [deploy guide](./index.md#choose-where-to-deploy) |
| Public address (`APP_URL`) | Required | The app won't start | Filled in automatically on Railway and Render. Set it yourself on Docker or when you add a custom domain |
| Secret (`AUTH_SECRET`) | Required | The app won't start | Generate once with `openssl rand -base64 32` and never change it |
| Email (`SMTP_URL`, `EMAIL_FROM`) | Optional, strongly recommended | You can create invoices and share their links, but invoices, reminders, receipts, invites and password resets aren't emailed. Emails are printed to the logs instead | [Email guide](./email.md#adding-this-to-an-existing-deploy) |
| File storage | Optional (local disk is the default) | Logos and profile photos are saved to local disk. Without a persistent volume they're lost on redeploy | [Storage guide](./storage.md#adding-this-to-an-existing-deploy) |
| Stripe card payments (`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`) | Optional | No **Pay** button; you record payments by hand | [Stripe guide](./stripe.md#adding-this-to-an-existing-deploy) |
| Google sign-in (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`) | Optional | People sign in with email and password | [Google guide](./google-oauth.md#adding-this-to-an-existing-deploy) |
| Open sign-up (`ALLOW_SIGNUP`) | Optional, off by default | Only invited people can create accounts | [First admin](./first-admin.md#open-sign-up) |
| Separate background worker (`ROLE`) | Optional | One process runs the web server and background jobs, which is right for most installs | Run a second copy of the image with `ROLE=worker` and set `ROLE=web` on the first. See the [Docker guide](./docker.md#run-background-jobs-separately-optional) |

## Instructions for AI agents

Follow these steps in order. Deploy the required pieces first, confirm the app is healthy, and only then offer the optional features, one at a time. Stop and ask the user whenever a step needs a decision, an account, or money.

### Part 1: deploy the required pieces

1. **Ask the user these questions first:**
   1. Where should it run: Railway, Render, or their own server with Docker? If they don't know, suggest Railway. Confirm that they accept the monthly cost (see [Self-hosting](./index.md#choose-where-to-deploy)).
   2. What address should it use? A custom domain such as `billing.example.com`, or the free address the host provides?
   3. Do they already know which optional features they want (see [Required vs optional](#required-vs-optional))? Note the answers, but don't set any of them up yet.
   **On Railway, use the template and skip steps 2 to 4.** It creates the app, Postgres, the uploads volume, the domain and `AUTH_SECRET`. Send the user https://railway.com/deploy/b4pESv, or, with the Railway CLI signed in to their account:

   ```sh
   mkdir invoicing-deploy && cd invoicing-deploy
   railway init --name "Invoicing"
   railway deploy --template b4pESv
   railway domain list --service Invoicing   # the public address
   ```

   Then continue at step 5.
2. **Get the code.** Clone the repository (or have the user fork it on GitHub first if they deploy to Railway or Render, so they control updates):

   ```sh
   git clone https://github.com/gtalarico/saas-clones.git
   cd saas-clones
   ```

3. **Generate the secret** and keep it somewhere safe outside the repository (a password manager or the hosting provider's variables). Changing it later signs everyone out.

   ```sh
   openssl rand -base64 32
   ```

4. **Deploy with the guide for the chosen platform:** [Railway](./railway.md), [Render](./render.md) or [Docker Compose](./docker.md). Use `apps/invoicing/Dockerfile` as the Dockerfile and build from the repository root. Set only `DATABASE_URL`, `APP_URL` and `AUTH_SECRET` for now, plus the persistent volume for uploads that the platform guide describes. On Docker Compose, also set `SMTP_URL`, or start with `--profile dev` for a local trial (see the [Docker guide](./docker.md#3-create-the-env-file)).
5. **Confirm the deploy is healthy.** Replace the address with the real one:

   ```sh
   curl -fsS https://billing.example.com/api/health
   # {"ok":true,"db":true,"version":"dev"}

   curl -fsS https://billing.example.com/api/bootstrap
   # ... "needsSetup":true ...
   ```

   Continue only when `/api/health` returns `200` with `"ok":true`. `"needsSetup":true` means nobody has claimed the admin account yet. If the app doesn't start, read its logs and see [Troubleshooting](#troubleshooting).
6. **Hand over the first-admin step.** Tell the user to open `https://<their address>/setup` right away and create the admin account themselves, so their password never passes through you. Until they do, anyone who finds the address can claim it. See [first admin](./first-admin.md).

### Part 2: offer the optional features, one at a time

Go through the list below in order. For each one, ask the user whether they want it now. If yes, follow that guide's "Adding this to an existing deploy" section, redeploy, run its check, and confirm it works before moving on to the next. If no, skip it; it can be added later.

1. **Email** ([email guide](./email.md#adding-this-to-an-existing-deploy)). Recommend it: Invoicing is far less useful without it. Check: the user invites a second address from **Settings > Members > Invite member**, or sends a test invoice to themselves, and the email arrives.
2. **File storage** ([storage guide](./storage.md#adding-this-to-an-existing-deploy)). Only needed if the platform has no persistent volume, or the user prefers a bucket. Check: upload the business logo, redeploy, and confirm it's still on the invoice.
3. **Stripe card payments** ([Stripe guide](./stripe.md#adding-this-to-an-existing-deploy)). Start with sandbox keys. Check: the [test payment](./stripe.md#test-a-payment) is recorded on the invoice.
4. **Google sign-in** ([Google guide](./google-oauth.md#adding-this-to-an-existing-deploy)). Check: `/api/bootstrap` shows `"google":true` and **Continue with Google** works.
5. **Open sign-up** ([first admin](./first-admin.md#open-sign-up)). Only if the user explicitly asks for it.

Finish by reporting the app address, where each secret is stored, and which optional features are on and off.

### Never do these

- Never commit `.env` files, `AUTH_SECRET`, SMTP passwords, Stripe keys or any other secret to git. Store them as hosting provider variables or in an untracked `.env` file.
- Never use live Stripe keys (`sk_live_`, `rk_live_`) unless the user explicitly says they are ready to take real payments.
- Never set `ALLOW_SIGNUP=true` unless the user asks for open sign-up.
- Never set `SEED_DEMO=true` on a real deployment. It creates an admin with a public password (`demo@example.com` / `demo-password`) and fake invoices.
- Never change or regenerate `AUTH_SECRET` on a running deployment.
- Never create paid resources (plans, databases, volumes, domains) without the user's confirmation.
- Never expose the Postgres port to the internet or delete database volumes.

## Quick deploy

- **Railway:** one click with the template, https://railway.com/deploy/b4pESv ([Railway guide](./railway.md#deploy-on-railway-template)). To build from your own fork instead, follow the manual steps with `RAILWAY_DOCKERFILE_PATH=apps/invoicing/Dockerfile`.
- **Render:** use the repository's `render.yaml` Blueprint. It also contains the Scheduler, so remove what you don't need first. See the [Render guide](./render.md).
- **Your own server:** `cd apps/invoicing`, create a `.env` file, then `docker compose up -d`. See the [Docker Compose guide](./docker.md).

## Environment variables

Only the first three are required. "Default" is the value used when the variable is unset.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DATABASE_URL` | Yes | | Postgres connection string. Use a database just for this app. |
| `APP_URL` | Yes, except on Railway and Render | The platform's address (`RAILWAY_PUBLIC_DOMAIN` or `RENDER_EXTERNAL_URL`) | Public address of the app, with `https://` and no trailing slash. Used for sign-in checks, links in emails, and Stripe return links. |
| `AUTH_SECRET` | Yes | | At least 32 characters. Signs sessions and file links. Never change it after launch. |
| `PORT` | No | `3000` | Port the server listens on. |
| `ROLE` | No | `all` | `all` runs the web server and background jobs in one process. `web` runs only the web server; `worker` runs only background jobs (for running jobs as a separate service). |
| `NODE_ENV` | No | `production` in the Docker image | Leave as is. |
| `ALLOW_SIGNUP` | No | `false` | `true` lets anyone create a member account. Otherwise only invited people can join. Accepts `true`, `false`, `1`, `0`. |
| `SEED_DEMO` | No | `false` | `true` loads a demo business, clients and invoices on first boot (only when the database has no users). For demos only. |
| `APP_NAME` | No | `Invoicing` | Name shown in the app and in emails. |
| `SMTP_URL` | No | | Outgoing email server as a URL, for example `smtp://resend:API_KEY@smtp.resend.com:587`. Unset means emails are printed to the logs. See [email](./email.md). |
| `EMAIL_FROM` | No | `Invoicing <noreply@HOST>`, where HOST is the host name of `APP_URL` | Sender of all emails, for example `Billing <billing@example.com>`. Must be an address your email provider lets you send from. |
| `STRIPE_SECRET_KEY` | No | | Stripe secret or restricted key. Turns on the "Pay" button on online invoices. See [Stripe](./stripe.md). |
| `STRIPE_WEBHOOK_SECRET` | No | | Signing secret (`whsec_...`) of the Stripe webhook. Needed to mark invoices paid automatically. |
| `STORAGE_DRIVER` | No | `local` | `local` (disk) or `s3`. See [storage](./storage.md). |
| `STORAGE_LOCAL_DIR` | No | `./data/uploads` (`/app/data/uploads` in the Docker image) | Folder for uploads with the `local` driver. Put it on a persistent volume. |
| `S3_ENDPOINT` | No | AWS S3 | S3 API address for non-AWS providers. |
| `S3_REGION` | No | `auto` | Bucket region. Set it for AWS (for example `us-east-1`). |
| `S3_BUCKET` | With `s3` | | Bucket name. |
| `S3_ACCESS_KEY_ID` | With `s3` | | Access key ID. |
| `S3_SECRET_ACCESS_KEY` | With `s3` | | Secret access key. |
| `S3_FORCE_PATH_STYLE` | No | `false` | Set `true` when you set `S3_ENDPOINT` (works with every listed provider). See [storage](./storage.md). |
| `GOOGLE_CLIENT_ID` | No | | Google OAuth client ID. With the secret, turns on "Continue with Google". |
| `GOOGLE_CLIENT_SECRET` | No | | Google OAuth client secret. |

## First admin

Open `https://<your address>/setup` and fill in the organization name, your name, email, password and time zone, then click **Create admin account**. The page only works while the database has no users. Then fill in your business details (name, address, logo, payment instructions) in **Settings**, and invite people from **Settings > Members**. Details and lockout recovery are in [first admin](./first-admin.md).

## Updating

New versions run their database migrations on startup. Back up the database first, then redeploy from the latest code. See [updates and backups](./updates-backups.md).

## Troubleshooting

**The app exits right after starting with `Invalid configuration`.** The log lists each problem, for example:

```text
Invalid configuration:
  - DATABASE_URL: Invalid input: expected string, received undefined
  - APP_URL: APP_URL must be the public URL of this app, e.g. https://cal.example.com
  - AUTH_SECRET: AUTH_SECRET must be at least 32 characters
See .env.example for every option.
```

Fix the listed variables and restart. `APP_URL` must include `https://` (or `http://` for local testing). Yes/no variables accept only `true`, `false`, `1` or `0`. With `STORAGE_DRIVER=s3`, a missing setting gives `S3_BUCKET is required when STORAGE_DRIVER=s3` (and the same for the two key variables).

**`/api/health` returns `503` with `"db":false`, or the app crashes with a connection error.** The app can't reach Postgres. Check `DATABASE_URL` and that the database is running.

**Sign-in fails, or you are sent back to the sign-in page.** `APP_URL` must exactly match the address in the browser, including `https://` and without a trailing slash.

**"Sign-up is invite-only on this server".** The person has no invite. Invite them from **Settings > Members**, or set `ALLOW_SIGNUP=true` if you want open sign-up.

**Emails don't arrive.** Look for `[email:logged]` lines in the logs: they mean `SMTP_URL` is unset. If it is set, failures are recorded with the error message in the `email_log` table. See the [email guide](./email.md#troubleshooting).

**Clients paid by card but the invoice still shows as unpaid.** The Stripe webhook isn't reaching the app or isn't verified. See [Stripe troubleshooting](./stripe.md#troubleshooting).

**"Online payments aren't enabled".** `STRIPE_SECRET_KEY` is not set on the running app.

**Characters print as `?` in PDFs.** PDFs use the standard PDF fonts, which only cover Latin scripts. The online invoice shows every character correctly.

**The business logo disappears after a redeploy.** Uploads were stored on a disk that isn't persistent. Mount a volume at the uploads folder or switch to S3. See [storage](./storage.md).