StackBill Installation

Introduction

StackBill is a self-hosted invoicing and quoting tool built for developers. This documentation explains how to install StackBill locally from the GitHub repository.

Installation takes just a few minutes and allows you to run StackBill on your machine or on your own server.

---

Prerequisites

Before you begin, make sure you have installed:

• Node.js version 18 or higher

• npm or yarn

• PostgreSQL version 14 or higher (or MySQL/SQLite as alternatives)

• Git

Check your installed versions:

node --version
npm --version
git --version
psql --version

---

Clone the repository

Clone the StackBill GitHub repository to your machine:

git clone https://github.com/guttership/stackbill.git
cd stackbill

---

Install dependencies

Install Node.js dependencies with npm:

npm install

Or with yarn:

yarn install

---

Configure environment (.env)

Create a .env.local file at the project root by copying the example file:

Copy-Item .env.example .env.local

Open .env.local and configure the environment variables:

<h1>PostgreSQL database</h1>
DATABASE_URL=postgresql://stackbill:password@localhost:5432/stackbill
<h1>Application URL</h1>
NEXT_PUBLIC_APP_URL=http://localhost:3000

Important: Replace the placeholder values with your actual database credentials.

---

Configure PostgreSQL database

1. Create the database

Connect to PostgreSQL:

psql -U postgres

Create the user and database:

CREATE USER stackbill WITH PASSWORD 'password';
CREATE DATABASE stackbill OWNER stackbill;
GRANT ALL PRIVILEGES ON DATABASE stackbill TO stackbill;
\q

2. Run migrations

If the project uses Prisma, run the migrations:

npm run db:migrate

Or initialize the schema:

npm run db:push

---

Start the application

Start the development server:

npm run dev

The server starts on port 3000 by default.

You should see:

▲ Next.js
Local:        http://localhost:3000
Environments: .env.local
✓ Compiled

---

Access StackBill

Open your browser and navigate to:

http://localhost:3000

You will see the StackBill interface. You can now:

Create quotes

Generate invoices

Manage your clients

Integrate Clockify and Trello

---

Useful commands

<h1>Run in development mode</h1>
npm run dev
<h1>Build for production</h1>
npm run build
<h1>Run in production mode</h1>
npm run start
<h1>TypeScript type checking</h1>
npm run type-check
<h1>Linter</h1>
npm run lint

---

Deploy to production

On your own server (VPS/Dedicated)

Clone the repository on your server

Configure environment variables

Install dependencies: npm install

Run migrations

Build: npm run build

Start: npm start

Online database configuration

For a hosted PostgreSQL database:

DATABASE_URL=postgresql://stackbill_user:your_secure_password@db.example.com:5432/stackbill

Hosted database options:

• Railway: https://railway.app (Managed PostgreSQL)

• Render: https://render.com (PostgreSQL and deployment)

• AWS RDS: https://aws.amazon.com/rds/

• Digital Ocean: https://www.digitalocean.com/products/managed-databases/

• Heroku: https://www.heroku.com/postgres

Custom domain configuration

To access StackBill via your own domain (e.g., invoicing.yourcompany.com):

Point your domain to your server:

- Update DNS records at your registrar - Create an A record pointing to your server IP - Example: invoicing.yourcompany.com A 192.168.1.100

Configure HTTPS with Let's Encrypt:

npm install -g certbot
   sudo certbot certonly --standalone -d invoicing.yourcompany.com

Update application URL:

NEXT_PUBLIC_APP_URL=https://invoicing.yourcompany.com

Setup reverse proxy (Nginx):

server {
     listen 80;
     server_name invoicing.yourcompany.com;
     
     location / {
       proxy_pass http://localhost:3000;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection 'upgrade';
       proxy_set_header Host $host;
       proxy_cache_bypass $http_upgrade;
     }
   }

Deploy on Vercel

Vercel offers the simplest deployment for Next.js applications:

Push your code to GitHub:

git push origin main

Import project on Vercel:

- Go to https://vercel.com/new - Connect your GitHub account - Select the stackbill repository - Click "Import"

Configure environment variables:

- Go to "Settings" → "Environment Variables" - Add: - DATABASE_URL: your PostgreSQL URL - NEXT_PUBLIC_APP_URL: your Vercel URL or custom domain

Connect your custom domain:

- In "Settings" → "Domains" - Add your domain (e.g., invoicing.yourcompany.com) - Vercel automatically generates an SSL certificate

Automatic deployment:

Every push to main automatically redeploys your application.

Deploy on Railway

Railway is perfect for small projects:

Create a Railway account:

https://railway.app

Connect your GitHub:

- Click "Start New Project" - Select "Deploy from GitHub" - Authorize Railway to access your account

Create a PostgreSQL database:

- In the dashboard, click "Add a Database" - Select "PostgreSQL" - Railway automatically generates DATABASE_URL

Configure environment variables:

- In the StackBill service, go to "Variables" - Add: - NEXT_PUBLIC_APP_URL: your Railway URL

Generate a domain:

- Railway automatically generates a public URL - Or point your custom domain via DNS

Deploy with Docker

To deploy with Docker on any server:

Create a Dockerfile:

FROM node:18-alpine
   
   WORKDIR /app
   COPY package*.json ./
   RUN npm ci
   
   COPY . .
   RUN npm run build
   
   EXPOSE 3000
   CMD ["npm", "start"]

Create docker-compose.yml:

version: '3.8'
   services:
     stackbill:
       build: .
       ports:
         - "3000:3000"
       environment:
         DATABASE_URL: postgresql://stackbill:password@postgres:5432/stackbill
         NEXT_PUBLIC_APP_URL: http://localhost:3000
       depends_on:
         - postgres
     postgres:
       image: postgres:14
       environment:
         POSTGRES_USER: stackbill
         POSTGRES_PASSWORD: password
         POSTGRES_DB: stackbill
       volumes:
         - postgres_data:/var/lib/postgresql/data
   
   volumes:
     postgres_data:

Start the services:

docker-compose up -d

---

Troubleshooting

Server won't start

Check if port 3000 is already in use:

Get-NetTCPConnection -LocalPort 3000 -State Listen -ErrorAction SilentlyContinue

Kill the process if necessary:

$pid = Get-NetTCPConnection -LocalPort 3000 -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess
Stop-Process -Id $pid -Force

PostgreSQL connection error

Check that PostgreSQL is running:

Get-Service postgresql*

Verify your credentials in .env.local.

Dependency errors

Delete node_modules and reinstall:

Remove-Item -Recurse -Force node_modules
npm install

---

Support

For any questions or issues:

• Check the documentation: https://stackbill.tech

• Open an issue on GitHub: https://github.com/guttership/stackbill/issues

• Contact support: designmoiunmouton@gmail.com