How to Self-Host Crater with Docker Compose

What Is Crater?

Crater is a self-hosted invoicing and expense tracking app built with Laravel and Vue.js. It generates professional invoices, tracks expenses, manages customers, and produces financial reports. It replaces FreshBooks, Wave, or QuickBooks for freelancers and small businesses who want invoicing without a monthly subscription.

Note: Crater’s last release was v6.0.6 in March 2022. The project is effectively unmaintained — no security patches, no bug fixes, no new features. The code still works for basic invoicing, but consider Invoice Ninja for an actively maintained alternative.

GitHub: github.com/crater-invoice/crater

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 512 MB of free RAM
• A domain name (recommended for client-facing invoices)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  crater:
    image: craterapp/crater:6.0.6
    container_name: crater
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      APP_KEY: base64:generate_with_php_artisan_key_generate
      APP_URL: http://localhost:8080
      DB_CONNECTION: mysql
      DB_HOST: mysql
      DB_PORT: "3306"
      DB_DATABASE: crater
      DB_USERNAME: crater
      DB_PASSWORD: change_this_strong_password
      MAIL_DRIVER: smtp
      MAIL_HOST: smtp.example.com
      MAIL_PORT: "587"
      MAIL_USERNAME: your_email@example.com
      MAIL_PASSWORD: your_email_password
      MAIL_ENCRYPTION: tls
      MAIL_FROM_ADDRESS: invoices@yourdomain.com
      MAIL_FROM_NAME: "Your Business Name"
    volumes:
      - crater_data:/var/www/html/storage
    depends_on:
      mysql:
        condition: service_healthy
    networks:
      - crater

  mysql:
    image: mysql:8.0
    container_name: crater-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: change_this_root_password
      MYSQL_DATABASE: crater
      MYSQL_USER: crater
      MYSQL_PASSWORD: change_this_strong_password
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - crater

volumes:
  crater_data:
  mysql_data:

networks:
  crater:

Before starting:

• Change DB_PASSWORD and MYSQL_PASSWORD to the same strong password
• Change MYSQL_ROOT_PASSWORD to a different strong password
• Generate APP_KEY with: docker run --rm craterapp/crater:6.0.6 php artisan key:generate --show
• Configure MAIL settings for sending invoices via email
• Set APP_URL to your public domain if using a reverse proxy

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server-ip:8080 in your browser
2. Complete the installation wizard:
   • Verify system requirements (PHP extensions, writable directories)
   • Confirm database connection
   • Create your admin account
   • Set your company name, address, and currency
3. Go to Settings → Company to add your logo and business details
4. Configure tax rates under Settings → Tax Types

Configuration

Setting	Where	What It Does
Company info	Settings → Company	Business name, address, logo on invoices
Tax types	Settings → Tax Types	Define tax rates for line items
Invoice prefix	Settings → Preferences	Prefix for invoice numbers (e.g., INV-)
Payment modes	Settings → Payment Modes	Available payment methods on invoices
Currency	Settings → Preferences	Default currency for invoices
Email templates	Settings → Mail Configuration	Customize invoice email content

Reverse Proxy

Example Nginx Proxy Manager configuration:

Field	Value
Domain	invoices.yourdomain.com
Scheme	http
Forward Host	crater
Forward Port	8080
SSL	Request a new certificate

Update APP_URL to https://invoices.yourdomain.com after setting up SSL.

For more options: Reverse Proxy Setup

Backup

Back up the MySQL database:

docker exec crater-db mysqldump -u crater -p crater > crater_backup.sql

Back up uploaded files (logos, attachments):

docker run --rm -v crater_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/crater-storage-$(date +%Y%m%d).tar.gz -C /data .

For automated backup strategies: Backup Strategy

Troubleshooting

”500 Internal Server Error” After Setup

Symptom: Blank page or 500 error after installation wizard.

Fix: Check that APP_KEY is properly set and the database migration completed. View logs:

docker logs crater

Invoices Not Sending via Email

Symptom: Invoices created but email delivery fails.

Fix: Verify MAIL settings in environment variables. Test with a simple SMTP service first. Check that your SMTP provider allows the MAIL_FROM_ADDRESS domain.

PDF Invoice Generation Fails

Symptom: “Unable to generate PDF” error when downloading invoices.

Fix: Crater uses wkhtmltopdf for PDF generation. This should be pre-installed in the Docker image. If missing, check that the container has the required dependencies.

Resource Requirements

Resource	Usage
RAM	~200-400 MB (PHP + MySQL)
CPU	Low
Disk	~500 MB for application, minimal for data

Verdict

Crater does basic invoicing well — creating, sending, and tracking invoices for freelancers and small businesses. The interface is clean and the feature set covers the essentials. However, with no updates since March 2022, it’s not recommended for new deployments. Invoice Ninja is actively maintained, has more features (recurring invoices, client portal, payment gateway integration), and is the better choice for self-hosted invoicing. Use Crater only if you have a specific reason to prefer it over Invoice Ninja.

Frequently Asked Questions

Is Crater still being maintained?

No. Crater’s last release was in March 2022 and the GitHub repository shows minimal activity since then. For new invoicing deployments, Invoice Ninja is actively maintained and offers significantly more features. Crater still works for existing users, but don’t expect bug fixes or new features.

Can Crater handle recurring invoices?

Limited. Crater supports creating invoices manually and tracking their payment status, but recurring invoice automation is basic compared to Invoice Ninja. For businesses that need automated recurring billing with payment reminders, Invoice Ninja is the better choice.

Does Crater support payment gateways?

Crater supports PayPal and Stripe for online payments through client-facing invoice links. Clients receive an invoice email, click the payment link, and pay through the gateway. The integration is basic — no automatic reconciliation. Invoice Ninja offers more payment gateway options and better automation around payment processing.

Can I customize invoice templates in Crater?

Yes. Crater includes several invoice templates and lets you customize them with your logo, colors, company details, and custom fields. The PDF generation produces clean, professional invoices. For more complex template customization, you need to modify the Laravel Blade templates in the source code.

Does Crater support multiple currencies?

Yes. Crater supports creating invoices in different currencies and tracks exchange rates. Each client can be assigned a default currency. However, reporting and totals are per-currency — there’s no automatic conversion to a base currency for unified financial reporting.

Can multiple users access Crater?

Yes. Crater supports multiple user accounts with role-based access. Create staff accounts for team members who need to create invoices or manage clients. Admin users have full access; staff users can be restricted to specific functions. The web UI is responsive and works on mobile browsers.

Related

• Invoice Ninja: Full Invoicing Platform
• Invoice Ninja vs Crater
• Firefly III: Personal Budget Tracking
• Best Self-Hosted Budget Apps
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy