Codakey
Play
← Back to Invio

How to Deploy & Use Invio

Invio Deployment and Usage Guide

1. Prerequisites

Before installing Invio, ensure you have the following:

  • Deno runtime (version 1.45.0 or later) - Required for both backend and frontend
  • SQLite - Built-in via Deno SQLite module, no separate installation needed
  • Git - For cloning the repository
  • Chromium/Chrome - Required for PDF generation (can be installed automatically)
  • Node.js/npm (optional) - Only if you plan to modify or build from source
  • Reverse proxy (optional) - For production deployments (nginx, Apache, or Caddy recommended)

2. Installation

Clone the Repository

git clone https://github.com/kittendevv/Invio.git
cd Invio

Install Dependencies

Invio uses Deno as its runtime and package manager. No npm install or separate dependency installation is required.

Initialize the Database

The database will be automatically created and migrated when you first run the application. However, you can manually initialize it:

# Ensure the database directory exists (if using custom path)
mkdir -p /path/to/database/dir

# The database will be created at DATABASE_PATH (default: ./invio.db)

3. Configuration

Environment Variables

Copy the example environment file and customize it:

cp .env.example .env

Edit the .env file with your preferred settings:

# Database Configuration
DATABASE_PATH=./invio.db  # Path to SQLite database file
DEMO_DB_PATH=./demo.db    # Path to demo database (for demo mode)

# Server Configuration
PORT=3000                  # Port to run the server on
HOST=0.0.0.0              # Host to bind to
NODE_ENV=production       # Set to 'development' for dev mode

# Security Settings
JWT_SECRET=your-secret-key-here-change-this
JWT_TTL=86400             # JWT token lifetime in seconds (default: 24 hours)
SESSION_SECRET=another-secret-key-change-this

# Rate Limiting (Security)
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_ATTEMPTS=5
RATE_LIMIT_WINDOW_SECONDS=900  # 15 minutes
RATE_LIMIT_TRUST_PROXY=false   # Set to true behind reverse proxy

# Application Settings
APP_NAME=Invio
BASE_URL=http://localhost:3000  # Change for production
DEFAULT_LOCALE=en_US
DEFAULT_CURRENCY=USD
DEFAULT_TIMEZONE=UTC

# PDF Generation
CHROMIUM_PATH=auto        # 'auto' to download, or path to installed Chromium
PDF_TIMEOUT=30000         # PDF generation timeout in ms

# Demo Mode (for testing)
DEMO_MODE=false
DEMO_RESET_HOURS=24       # Reset demo data every X hours

Reverse Proxy Configuration

When deploying behind a reverse proxy, ensure proper headers are set:

For nginx:

location / {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Set in .env:

RATE_LIMIT_TRUST_PROXY=true

4. Build & Run

Development Mode

# Start the development server
deno task dev

# Or run directly
deno run --allow-read --allow-write --allow-net --allow-env --allow-run backend/src/server.ts

Production Mode

# Set environment to production
export NODE_ENV=production

# Run with production permissions
deno run \
  --allow-read \
  --allow-write \
  --allow-net \
  --allow-env \
  --allow-run \
  backend/src/server.ts

Using Deno Tasks (Recommended)

The project includes predefined tasks in deno.json:

# Start development server with hot reload
deno task dev

# Run tests
deno task test

# Format code
deno task fmt

# Lint code
deno task lint

# Type check
deno task check

First-Time Setup

  1. Access the application at http://localhost:3000
  2. Create your first admin account through the setup wizard
  3. Configure your business settings (company name, address, tax information)
  4. Start creating invoices, customers, and products

5. Deployment

Platform Recommendations

Option 1: Traditional VPS (Recommended)

  • Platforms: DigitalOcean, Linode, AWS EC2, Vultr

  • Setup:

    # Install Deno
curl -fsSL https://deno.land/install.sh | sh

# Set up systemd service
sudo nano /etc/systemd/system/invio.service

    Example systemd service file:

    [Unit]
Description=Invio Invoicing
After=network.target

[Service]
Type=simple
User=invio
WorkingDirectory=/opt/invio
Environment="DENO_DIR=/opt/invio/.deno"
Environment="PATH=/home/invio/.deno/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/home/invio/.deno/bin/deno run \
  --allow-read \
  --allow-write \
  --allow-net \
  --allow-env \
  --allow-run \
  backend/src/server.ts
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Option 2: Docker Deployment Create a Dockerfile:

FROM denoland/deno:alpine

WORKDIR /app

# Copy source code
COPY . .

# Set permissions
RUN chown -R deno:deno /app

# Run as non-root user
USER deno

# Cache dependencies
RUN deno cache backend/src/server.ts

# Expose port
EXPOSE 3000

# Start the application
CMD ["run", "--allow-read", "--allow-write", "--allow-net", "--allow-env", "--allow-run", "backend/src/server.ts"]

Build and run:

docker build -t invio .
docker run -p 3000:3000 -v ./data:/app/data invio

Option 3: Railway/Deno Deploy

  • Use deno deploy configuration in deno.json
  • Set environment variables in the platform dashboard
  • Ensure persistent storage for SQLite database

Database Persistence

For production deployments, ensure your database file is persisted:

  • Use volume mounts in Docker
  • Store in persistent directory on VPS
  • Regular backups of the SQLite file

SSL/TLS Configuration

Always use HTTPS in production:

  1. Obtain SSL certificates (Let's Encrypt recommended)
  2. Configure reverse proxy with SSL termination
  3. Set BASE_URL to https://yourdomain.com
  4. Enable HSTS in your reverse proxy configuration

6. Troubleshooting

Common Issues

Issue: "Permission denied" errors

# Solution: Ensure all required permissions are granted
deno run --allow-read --allow-write --allow-net --allow-env --allow-run backend/src/server.ts

Issue: PDF generation fails

# Solution 1: Let the application download Chromium automatically
# Set in .env: CHROMIUM_PATH=auto

# Solution 2: Install Chromium manually
# Ubuntu/Debian: sudo apt-get install chromium
# Set in .env: CHROMIUM_PATH=/usr/bin/chromium

Issue: Database errors on startup

# Solution 1: Check file permissions
chmod 644 ./invio.db
chmod 755 $(dirname ./invio.db)

# Solution 2: Ensure database directory exists
mkdir -p /path/to/database

Issue: Rate limiting blocks legitimate requests

# Solution: Adjust rate limiting settings in .env
RATE_LIMIT_MAX_ATTEMPTS=10
RATE_LIMIT_WINDOW_SECONDS=300  # 5 minutes

Issue: Application doesn't start on configured port

# Solution: Check if port is already in use
sudo lsof -i :3000
# Kill conflicting process or change PORT in .env

Issue: Demo mode won't disable

# Solution: Ensure DEMO_MODE=false in .env
# And remove any demo database files
rm -f demo.db

Logs and Debugging

Enable debug logging by setting environment variables:

export DEBUG=invio:*
export NODE_ENV=development

Check application logs:

  • Systemd: sudo journalctl -u invio.service -f
  • Docker: docker logs -f container_name
  • Direct run: Check console output

Backup and Recovery

Regularly backup your SQLite database:

# Simple backup
cp invio.db invio.db.backup-$(date +%Y%m%d)

# Backup with SQLite .dump
sqlite3 invio.db .dump > invio-backup-$(date +%Y%m%d).sql

To restore from backup:

# Replace database file
cp invio.db.backup invio.db

# Or restore from SQL dump
sqlite3 invio.db < invio-backup.sql

Getting Help

  • Check the GitHub Wiki for documentation
  • Review existing GitHub Issues
  • Visit the Live Demo to see the application in action
  • For security concerns, review the security headers and rate limiting configuration in the source code
← Project overviewView alternatives to Invio →