Deploying Akaunting

Introduction

Akaunting is a powerful, free, and open-source accounting software built with Laravel that helps businesses manage their finances with ease. It offers features like invoicing, expense tracking, financial reporting, inventory management, and multi-currency support. Designed for small to medium-sized businesses and freelancers, Akaunting provides a modern, intuitive interface for managing your accounting needs without the complexity and cost of traditional accounting software.

Deploying Akaunting on Klutch.sh gives you a reliable, scalable platform for hosting your financial data with production-grade infrastructure, persistent storage for your accounting records, and automated deployment workflows. Whether you’re running a startup, managing client accounts, or handling personal finances, this guide walks you through deploying Akaunting using Docker to ensure a reproducible, secure setup.

This comprehensive guide covers everything you need to deploy Akaunting successfully: from creating your Dockerfile to configuring database connections, setting up persistent volumes for uploads and storage, managing environment variables, and implementing production best practices for security and performance.

Prerequisites

Before you begin deploying Akaunting on Klutch.sh, ensure you have the following:

A Klutch.sh account (sign up here)
A GitHub account and repository for your Akaunting project
Basic familiarity with Docker, environment variables, and database management
A MySQL or PostgreSQL database (you can provision one on Klutch.sh or use an external managed database service)
Understanding of Laravel applications (helpful but not required)

What You’ll Deploy

By the end of this guide, you’ll have:

A fully functional Akaunting installation running on Klutch.sh
Persistent storage for file uploads, documents, and application data
Database connectivity to MySQL or PostgreSQL for storing accounting records
Secure environment variable configuration for credentials and secrets
Production-ready setup with proper permissions and security configurations
A Docker-based deployment that’s reproducible and easy to maintain

Understanding Akaunting Architecture

Akaunting is built on the Laravel PHP framework and requires:

PHP 8.1 or higher with required extensions (OpenSSL, PDO, Mbstring, Tokenizer, XML, Ctype, JSON, BCMath)
Web server (Apache or Nginx)
MySQL 5.7+ or PostgreSQL 9.5+ database for storing accounting data
File storage for uploads, documents, invoices, and application assets
Composer for dependency management

The application runs on port 80 by default when using Apache, which we’ll map to port 8000 for internal routing on Klutch.sh.

1. Prepare Your Akaunting Repository

Create a new GitHub repository for your Akaunting deployment or fork an existing one.
In your repository root, you’ll create a Dockerfile that defines the container image for Akaunting. This ensures reproducible builds.
Keep sensitive data (database credentials, API keys) out of your repository. We’ll use Klutch.sh environment variables to manage secrets securely.

Organize your repository structure:

akaunting-deployment/
├── Dockerfile
├── .dockerignore
├── docker-compose.yml (for local development only)
└── README.md

Create a .dockerignore file to exclude unnecessary files from the Docker build:

.git
.github
.env
node_modules
storage/logs/*
storage/framework/cache/*
storage/framework/sessions/*
storage/framework/views/*

For more details on setting up your repository and connecting to GitHub, refer to the Klutch.sh Quick Start Guide.

2. Sample Dockerfile for Akaunting

Below is a production-ready Dockerfile that sets up Akaunting with Apache, all required PHP extensions, and proper permissions. This Dockerfile installs Akaunting from the official release, configures the web server, and prepares the application for deployment.

FROM php:8.2-apache

# Set working directory
WORKDIR /var/www/html

# Install system dependencies and PHP extensions
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    libzip-dev \
    zip \
    unzip \
    libfreetype6-dev \
    libjpeg62-turbo-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) \
    pdo \
    pdo_mysql \
    mbstring \
    exif \
    pcntl \
    bcmath \
    gd \
    zip \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Download and install Akaunting
ARG AKAUNTING_VERSION=3.1.0
RUN curl -L -o akaunting.zip "https://github.com/akaunting/akaunting/releases/download/${AKAUNTING_VERSION}/Akaunting_${AKAUNTING_VERSION}-Stable.zip" \
    && unzip -q akaunting.zip -d /var/www/html \
    && rm akaunting.zip \
    && chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html/storage /var/www/html/bootstrap/cache

# Enable Apache mod_rewrite for Laravel routing
RUN a2enmod rewrite

# Configure Apache to serve Akaunting
RUN sed -i 's!/var/www/html!/var/www/html/public!g' /etc/apache2/sites-available/000-default.conf \
    && echo "<Directory /var/www/html/public>" >> /etc/apache2/sites-available/000-default.conf \
    && echo "    AllowOverride All" >> /etc/apache2/sites-available/000-default.conf \
    && echo "    Require all granted" >> /etc/apache2/sites-available/000-default.conf \
    && echo "</Directory>" >> /etc/apache2/sites-available/000-default.conf

# Set proper permissions for storage and cache
RUN chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache

# Expose port 80
EXPOSE 80

# Start Apache in foreground
CMD ["apache2-foreground"]

Key features of this Dockerfile:

Uses PHP 8.2 with Apache for optimal Laravel performance
Installs all required PHP extensions for Akaunting
Downloads the official Akaunting release from GitHub
Configures Apache with proper document root and rewrite rules
Sets correct file permissions for Laravel storage directories
Installs Composer for dependency management

Note: You can customize the AKAUNTING_VERSION argument to deploy a specific version. Check Akaunting releases for available versions.

3. Local Development with Docker Compose

For local development and testing before deploying to Klutch.sh, you can use Docker Compose to run Akaunting with a MySQL database. Note: Klutch.sh does not support Docker Compose for deployment—this is only for local development.

Create a docker-compose.yml file in your repository:

version: '3.8'

services:
  akaunting:
    build: .
    ports:
      - "8000:80"
    environment:
      - DB_HOST=mysql
      - DB_PORT=3306
      - DB_DATABASE=akaunting
      - DB_USERNAME=akaunting
      - DB_PASSWORD=secure_password
      - APP_URL=http://localhost:8000
      - APP_ENV=local
      - APP_DEBUG=true
    volumes:
      - akaunting-storage:/var/www/html/storage
      - akaunting-uploads:/var/www/html/public/uploads
    depends_on:
      - mysql

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_DATABASE=akaunting
      - MYSQL_USER=akaunting
      - MYSQL_PASSWORD=secure_password
      - MYSQL_ROOT_PASSWORD=root_password
    volumes:
      - mysql-data:/var/lib/mysql
    ports:
      - "3306:3306"

volumes:
  akaunting-storage:
  akaunting-uploads:
  mysql-data:

To test locally:

# Build and start containers
docker-compose up -d

# View logs
docker-compose logs -f akaunting

# Access Akaunting at http://localhost:8000
# Stop containers
docker-compose down

Once you’ve verified everything works locally, proceed to deploy on Klutch.sh.

4. Deploying to Klutch.sh

Now that you have your Dockerfile ready, let’s deploy Akaunting to Klutch.sh.

Push your code to GitHub

Commit your Dockerfile and any configuration files to your repository, then push to GitHub:
Terminal window
```
git add .
git commit -m "Add Akaunting Dockerfile for Klutch.sh deployment"
git push origin main
```
Log in to Klutch.sh

Navigate to klutch.sh/app and log in to your account.
Create a new project (if you haven’t already)

Projects help organize your applications. Give it a meaningful name like “Accounting Apps” or “Akaunting Production”.
Create a new app
- Click “Create New App”
- Select your GitHub repository containing the Dockerfile
- Select the branch you want to deploy (e.g., main)
- Klutch.sh will automatically detect the Dockerfile in your repository root
Configure traffic type and port
- Traffic Type: Select HTTP (Akaunting is a web application)
- Internal Port: Set to 80 (this is the port Apache listens on inside the container)
When users access your Akaunting instance, Klutch.sh routes external traffic to port 80 inside your container.
Configure deployment settings
- Region: Choose the region closest to your users for better performance
- Compute: Select an appropriate instance size (start with 1 CPU / 2GB RAM minimum)
- Instances: Start with 1 instance; you can scale later based on traffic
Set up persistent volumes

Akaunting requires persistent storage for uploaded files, documents, invoices, and application data. Create volumes for:
- Storage directory: Mount path /var/www/html/storage with size 10GB or more
- Uploads directory: Mount path /var/www/html/public/uploads with size 10GB or more
In the Klutch.sh dashboard:
- Click “Add Volume”
- Enter the mount path: /var/www/html/storage
- Set the size (e.g., 10GB)
- Repeat for /var/www/html/public/uploads
Configure environment variables

Add the following environment variables in the Klutch.sh dashboard (mark sensitive values as secrets):

Required:
- APP_URL - Your application URL (e.g., https://example-app.klutch.sh)
- APP_ENV - Set to production
- APP_DEBUG - Set to false for production
- APP_KEY - Laravel application key (generate with php artisan key:generate)
- DB_HOST - Your database hostname
- DB_PORT - Database port (3306 for MySQL, 5432 for PostgreSQL)
- DB_DATABASE - Database name (e.g., akaunting)
- DB_USERNAME - Database username
- DB_PASSWORD - Database password (mark as secret)
Optional but recommended:
- MAIL_DRIVER - Email driver (smtp, mailgun, ses, etc.)
- MAIL_HOST - SMTP server hostname
- MAIL_PORT - SMTP port (587 for TLS, 465 for SSL)
- MAIL_USERNAME - SMTP username
- MAIL_PASSWORD - SMTP password (mark as secret)
- MAIL_ENCRYPTION - tls or ssl
- MAIL_FROM_ADDRESS - Sender email address
- MAIL_FROM_NAME - Sender name
Deploy your app

Click “Create” to start the deployment. Klutch.sh will:
- Pull your repository from GitHub
- Build the Docker image using your Dockerfile
- Create and attach persistent volumes
- Inject environment variables
- Start the container
- Route traffic to your app
Monitor the build process

Watch the build logs in the Klutch.sh dashboard. The first build may take 5-10 minutes as Docker installs dependencies and downloads Akaunting.

Once deployment completes, you’ll receive a URL like https://example-app.klutch.sh where your Akaunting instance is accessible.

5. Database Setup

Akaunting requires a MySQL or PostgreSQL database. You have several options:

Option A: Use an External Managed Database

You can use managed database services like:

These services handle backups, scaling, and high availability for you.

Option B: Deploy MySQL/PostgreSQL on Klutch.sh

You can deploy a database container on Klutch.sh:

Create a new app in your Klutch.sh project
Use the official MySQL or PostgreSQL Docker image
Select TCP as the traffic type (databases use TCP, not HTTP)
Set the internal port to 3306 (MySQL) or 5432 (PostgreSQL)
Attach a persistent volume to /var/lib/mysql or /var/lib/postgresql/data
Set database environment variables (root password, database name, user)
To connect your Akaunting app to the database, use port 8000 (Klutch.sh maps TCP traffic to port 8000 externally)

Example database connection from Akaunting:

DB_HOST=your-database-app.klutch.sh
DB_PORT=8000
DB_DATABASE=akaunting
DB_USERNAME=akaunting
DB_PASSWORD=secure_password

Database Initialization

On first launch, Akaunting will guide you through the installation wizard at your app URL. You’ll need to:

Accept the license agreement
Verify system requirements
Enter your database credentials
Create your admin account
Configure company information

After installation, remove or disable the installer by setting:

APP_INSTALLED=true

6. Environment Variables Reference

Here’s a comprehensive list of environment variables for Akaunting:

Application Settings

Variable	Description	Example	Required
`APP_ENV`	Application environment	`production`	Yes
`APP_DEBUG`	Enable debug mode	`false`	Yes
`APP_URL`	Your app URL	`https://example-app.klutch.sh`	Yes
`APP_KEY`	Laravel encryption key	`base64:...`	Yes
`APP_LOCALE`	Default language	`en-GB`	No
`APP_TIMEZONE`	Default timezone	`UTC`	No

Database Configuration

Variable	Description	Example	Required
`DB_CONNECTION`	Database type	`mysql` or `pgsql`	Yes
`DB_HOST`	Database hostname	`db.example.com`	Yes
`DB_PORT`	Database port	`3306` or `5432`	Yes
`DB_DATABASE`	Database name	`akaunting`	Yes
`DB_USERNAME`	Database user	`akaunting_user`	Yes
`DB_PASSWORD`	Database password	`secure_password`	Yes
`DB_PREFIX`	Table prefix	`aka_`	No

Mail Configuration

Variable	Description	Example	Required
`MAIL_DRIVER`	Mail driver	`smtp`	No
`MAIL_HOST`	SMTP hostname	`smtp.gmail.com`	No
`MAIL_PORT`	SMTP port	`587`	No
`MAIL_USERNAME`	SMTP username	`user@example.com`	No
`MAIL_PASSWORD`	SMTP password	`password`	No
`MAIL_ENCRYPTION`	Encryption type	`tls`	No

Security & Performance

Variable	Description	Example	Required
`SESSION_DRIVER`	Session storage	`file` or `redis`	No
`CACHE_DRIVER`	Cache driver	`file` or `redis`	No
`QUEUE_CONNECTION`	Queue driver	`sync` or `redis`	No

Important: Always mark sensitive variables (passwords, API keys) as secrets in the Klutch.sh dashboard to prevent them from appearing in logs.

7. Post-Deployment Configuration

After your app is deployed and running:

Access the installation wizard

Navigate to your app URL (e.g., https://example-app.klutch.sh). The Akaunting installation wizard will guide you through initial setup.
Complete database migration

The installer will create necessary database tables and seed initial data.
Create your admin account

Set up your administrator credentials during installation. Use a strong password.
Configure company information

Enter your company name, email, address, and tax information.
Set up email notifications (optional)

Configure SMTP settings in the Akaunting admin panel or via environment variables for invoice emails and notifications.
Install additional modules (optional)

Akaunting supports various modules and apps from the Akaunting App Store for extended functionality.

8. Persistent Storage Best Practices

Akaunting stores important data in several directories that must persist across deployments:

Required Persistent Volumes

Storage Directory (/var/www/html/storage)
- Contains logs, cache, sessions, and framework files
- Minimum size: 5GB
- Critical for application state
Uploads Directory (/var/www/html/public/uploads)
- Contains uploaded documents, invoices, receipts
- Size depends on your usage (start with 10GB)
- Critical for document management

Volume Management Tips

Regular backups: Create automated backups of your volumes to prevent data loss
Monitor disk usage: Set up alerts when volumes reach 80% capacity
Scaling volumes: You can increase volume size in the Klutch.sh dashboard as needed
File permissions: Ensure the web server user (www-data) has write permissions

9. Security Best Practices

Protecting your financial data is critical. Follow these security recommendations:

Application Security

Keep Akaunting updated: Regularly update to the latest version for security patches
Strong passwords: Use complex passwords for admin accounts and database
Two-factor authentication: Enable 2FA for all user accounts
SSL/TLS: Always use HTTPS (Klutch.sh provides this automatically)
Firewall rules: Restrict database access to only the Akaunting app

Environment Variables Security

Mark all sensitive values as secrets in Klutch.sh
Never commit .env files or credentials to Git
Rotate database passwords regularly
Use strong random keys for APP_KEY

Database Security

Create a dedicated database user for Akaunting with minimal privileges
Enable SSL connections between app and database if supported
Regular database backups (daily minimum for production)
Keep database software updated

File Upload Security

Configure file upload limits in PHP settings
Restrict allowed file types in Akaunting settings
Regularly scan uploads for malware
Set proper file permissions (644 for files, 755 for directories)

10. Monitoring and Maintenance

Health Checks

Monitor your Akaunting deployment:

Application logs: Check logs for errors via the Klutch.sh dashboard
Database connections: Monitor active connections and query performance
Disk usage: Watch persistent volume usage
Response times: Set up uptime monitoring with tools like UptimeRobot

Performance Optimization

Enable caching: Use Redis or Memcached for session and cache storage
Optimize database: Regular OPTIMIZE TABLE commands and proper indexing
CDN for assets: Use a CDN for static assets to reduce load
Queue processing: Use Laravel queues for time-consuming tasks like email sending

Backup Strategy

Implement a comprehensive backup plan:

Database backups: Daily automated backups with 30-day retention
Volume backups: Weekly backups of storage and uploads directories
Configuration backups: Keep environment variables documented
Test restores: Regularly test your backup restoration process

Updating Akaunting

To update to a new version:

Review the Akaunting update guide
Backup your database and volumes
Update the AKAUNTING_VERSION in your Dockerfile
Commit and push changes to GitHub
Klutch.sh will rebuild and redeploy with the new version
Run any required database migrations

11. Scaling Your Akaunting Deployment

As your business grows, you may need to scale your Akaunting deployment:

Vertical Scaling (Increase Resources)

Upgrade compute resources in Klutch.sh (more CPU/RAM)
Increase persistent volume sizes as data grows
Optimize database performance with better hardware

Horizontal Scaling (Multiple Instances)

For high availability, you can run multiple Akaunting instances:

Increase the instance count in Klutch.sh settings
Use a shared database (not container-based)
Configure session storage with Redis (not file-based)
Use shared storage for uploads (S3-compatible object storage)

Note: File-based sessions don’t work well with multiple instances. Update your environment variables:

SESSION_DRIVER=redis
CACHE_DRIVER=redis
REDIS_HOST=your-redis-host
REDIS_PORT=6379

12. Troubleshooting Common Issues

Application Won’t Start

Symptoms: Container exits immediately or shows errors in logs

Solutions:

Check database connectivity (verify credentials and hostname)
Ensure APP_KEY is set (generate with php artisan key:generate)
Verify persistent volumes are mounted correctly
Check file permissions on storage directories

Database Connection Errors

Symptoms: “SQLSTATE[HY000] [2002] Connection refused”

Solutions:

Verify DB_HOST and DB_PORT are correct
For Klutch.sh databases using TCP traffic, ensure you’re connecting to port 8000
Check database is running and accepting connections
Verify database credentials are correct
Ensure database exists and user has proper permissions

File Upload Failures

Symptoms: Unable to upload documents or invoices

Solutions:

Check persistent volume is attached to /var/www/html/public/uploads
Verify file permissions: chown -R www-data:www-data /var/www/html/public/uploads
Check PHP upload limits in php.ini (increase upload_max_filesize and post_max_size)
Ensure volume has sufficient free space

Performance Issues

Symptoms: Slow page loads, timeouts

Solutions:

Enable Laravel caching: php artisan cache:clear then php artisan config:cache
Optimize database with proper indexes
Upgrade compute resources in Klutch.sh
Enable Redis for caching and sessions
Check for slow database queries in logs

Session Errors

Symptoms: Constant logouts, “Session expired” messages

Solutions:

Verify storage directory is writable
If using multiple instances, switch to Redis for sessions
Clear session files: php artisan session:clear
Check SESSION_LIFETIME environment variable

13. Getting Started: Sample Accounting Workflow

Once Akaunting is deployed, here’s a quick workflow to get started:

Initial Setup

Log in to your Akaunting instance at your Klutch.sh URL
Complete company profile:
- Go to Settings → Company
- Add company name, address, logo, and tax information
Set up chart of accounts:
- Navigate to Settings → Charts of Accounts
- Review default accounts or customize for your business

Create Your First Invoice

// Example: Creating an invoice via Akaunting API
$invoice = [
    'document_number' => 'INV-001',
    'issued_at' => date('Y-m-d'),
    'due_at' => date('Y-m-d', strtotime('+30 days')),
    'amount' => 1500.00,
    'currency_code' => 'USD',
    'contact_id' => 1,
    'items' => [
        [
            'name' => 'Web Development Services',
            'quantity' => 1,
            'price' => 1500.00,
        ]
    ]
];

// Make API request to create invoice
// API documentation: https://akaunting.com/docs/api

Track Expenses

Navigate to Expenses → Bills
Click Add New to record a business expense
Upload receipts to the bill for record-keeping
Categorize expense for accurate reporting

Generate Financial Reports

Go to Reports → Income vs Expense
Select date range and filters
Export reports in PDF or Excel format
Share with accountants or stakeholders

14. Advanced Configuration

Custom Domain Setup

To use your own domain (e.g., accounting.yourcompany.com):

In Klutch.sh dashboard, go to your app settings
Add custom domain in the domains section
Update DNS records as instructed by Klutch.sh
Update APP_URL environment variable to match your domain
SSL certificates are automatically provisioned by Klutch.sh

API Integration

Akaunting provides a RESTful API for integrations:

API Documentation: Akaunting API Docs
Authentication: Use API tokens generated in Settings → API Tokens
Base URL: https://example-app.klutch.sh/api

Example API request:

curl -X GET \
  https://example-app.klutch.sh/api/invoices \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json'

Multi-Company Setup

Akaunting supports managing multiple companies in a single installation:

Go to Settings → Companies
Click Add New Company
Configure company details and settings
Switch between companies using the dropdown in the header

Automated Backups

Set up automated backups with a cron job or scheduled task:

# Backup script example
#!/bin/bash

# Backup database
mysqldump -h $DB_HOST -u $DB_USERNAME -p$DB_PASSWORD $DB_DATABASE > backup-$(date +%Y%m%d).sql

# Backup uploads and storage
tar -czf storage-backup-$(date +%Y%m%d).tar.gz /var/www/html/storage /var/www/html/public/uploads

# Upload to S3 or backup storage
# aws s3 cp backup-$(date +%Y%m%d).sql s3://your-backup-bucket/

15. Migration from Other Platforms

If you’re migrating from another platform to Klutch.sh:

From Shared Hosting

Export your database from cPanel/phpMyAdmin
Download all files via FTP/SFTP
Create Dockerfile following this guide
Import database to your new database on/for Klutch.sh
Upload storage files to persistent volumes
Update environment variables
Deploy to Klutch.sh

From Another Container Platform

Export your existing Docker configuration
Adapt Dockerfile if necessary
Export database and storage volumes
Import to Klutch.sh persistent volumes
Update environment variables for Klutch.sh
Deploy and test

Resources

Conclusion

You now have a comprehensive, production-ready Akaunting deployment on Klutch.sh. This setup provides secure financial data management, persistent storage for your accounting records, automated deployments via GitHub, and the flexibility to scale as your business grows.

Remember to:

Keep Akaunting updated for security and features
Perform regular backups of database and volumes
Monitor resource usage and scale as needed
Follow security best practices for handling financial data
Review logs periodically for errors or issues

With Akaunting running on Klutch.sh, you have a powerful, cost-effective accounting solution that grows with your business needs. For additional help, refer to the resources section above or reach out to the Klutch.sh support team.

Happy accounting! 🎉