DeskMint Backend

DeskMint is a source-available web application designed to simplify workflows for small businesses, teams, and organizations. It streamlines client communication, document management, invoicing, and task tracking through a centralized platform.

Project Overview

This repository contains the backend for DeskMint. The backend is responsible for handling the business logic, API endpoints, database management, authentication, and integration services. It is designed to work seamlessly with the deskmint-frontend repository.

Tech Stack

• PHP 8.3
• Laravel (Modern PHP web framework)
• MySQL 8.0 (Relational database)
• Redis (Cache and queue driver)
• Sanctum (Token-based API authentication)
• Laravel Queues (for background jobs with Supervisor)
• Laravel Scheduler (for recurring tasks)
• Filesystem Abstraction (for local and cloud storage)
• Third-party Integrations (planned for email, cloud storage, etc.)

Features

• RESTful API: Built for modern SPAs/PWA DeskMint frontend
• Authentication: Secure custom token-based login and user access control
• Recurring Tasks: Schedule and auto-generate repeatable items
• Smart Document Handling: File upload, tagging, and structured storage
• Background Jobs: Redis-powered queue system with automatic worker management
• Email Testing: Built-in Mailpit for local email testing

Installation

Prerequisites (Docker - Recommended)

• Docker and Docker Compose installed
• Git

Setup with Docker (Recommended)

1. Clone the Repository

git clone git@github.com:parthmp/deskmint-backend.git
cd deskmint-backend

2. Build and Start Docker Containers

docker compose up --build

Important: Do not use the -d flag for the first build. Wait for Docker Compose to build all images and start accepting connections.

3. Run the Setup Script

Once the containers are running and accepting connections, press d in existing terminal to detach it and run:

chmod +x docker.dev/setup.sh
./docker.dev/setup.sh

This script will:

• Copy .env.example to .env
• Install Composer dependencies
• Generate application key
• Run database migrations
• Set proper file permissions

Once script finishes running, open .env file, and set value for TURNSTILE_SECRET, get your cloudflare turnstile secret key from cloudflare

Shorter Artisan Command to avoid file permissions altogather! (Everything will be owned by www-data)

To make artisan commands easier, add this alias to your shell:

nano ~/.bashrc

Scroll to the bottom and add below command

alias artisan='docker compose exec -u www-data app php artisan'

Then, press Ctrl + O -> Enter -> Ctrl + X, Reload your shell configuration

source ~/.bashrc

Test the alias

artisan list

4. Access the Application

Once setup is complete, you can access the following services:

• Laravel App: http://localhost:8080
• Mailpit (Email Testing): http://localhost:8025
• Redis: localhost:6379
• MySQL: localhost:3306

Managing Docker Containers

Stopping containers:

docker compose down

Starting containers (after initial setup):

docker compose up -d

Restarting containers:

docker compose restart

Note: You only need to run setup.sh once during initial setup. After restarts, everything including queue workers will start automatically.

Rebuilding After Changes

If you modify Dockerfile or docker-compose.yml:

docker compose down
docker compose up -d --build

Your data, .env, and vendor/ directory will persist - no need to run setup.sh again.

Running Artisan Commands

docker compose exec app php artisan test #to run phpunit tests

Alternative Setup - Without Docker (Not Recommended)

If you prefer to run without Docker:

Prerequisites

• PHP 8.3 or higher
• Composer
• MySQL 8.x
• Redis (optional, can use database driver)
• Supervisor (for queue workers, also php artisan queue could be used)
• Laravel CLI (optional but useful)

Installation Steps

git clone https://github.com/parthmp/deskmint-backend.git
cd deskmint-backend
composer install
cp .env.example .env
php artisan key:generate

Edit the .env file with your database and environment configuration, then run:

php artisan migrate
php artisan serve

Queue Worker

php artisan queue:work

API Documentation

All endpoints are prefixed with /api. Authentication is handled using Laravel Sanctum.

For available routes, check:

php artisan route:list
# or view the file directly
routes/api.php

Environment Variables

Key environment variables in .env:

APP_ENV=local
APP_KEY=                    # Generated by setup script
DB_CONNECTION=mysql
DB_HOST=db                  # 'db' for Docker, '127.0.0.1' for local
DB_DATABASE=deskmint
DB_USERNAME=deskmint
DB_PASSWORD=deskmint_password

CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_HOST=redis          # 'redis' for Docker, '127.0.0.1' for local
MAIL_MAILER=smtp
MAIL_HOST=mailpit         # Built-in email testing
MAIL_PORT=1025

TURNSTILE_SECRET=		  # should be set to your turnstile secret key

Development

Running Tests

With docker

docker compose exec app php artisan test

Without docker

php artisan test

Checking Queue Worker Status

docker compose exec app supervisorctl status

Viewing Logs

docker compose exec app tail -f storage/logs/laravel.log
docker compose exec app tail -f storage/logs/worker.log

License

🔒 License: DeskMint is source-available software licensed under the Elastic License 2.0. You are free to view, modify, and self-host it for personal and commercial usage. However, you are not allowed to offer it as a hosted service or sell it as a SaaS product without a commercial license.

Support

For issues and questions, please use the GitHub Issues page.