Skip to main content

​
Requirements

Before installing Doss, ensure your server meets the following requirements:
RequirementVersion
PHP8.2 or higher
DatabaseMySQL 8.0+ or PostgreSQL 13+
Composer2.x
Node.js18 LTS or higher
npm9+
Redis6+ (required for queue processing)
Web serverNginx or Apache
Required PHP extensions: pdo, pdo_mysql (or pdo_pgsql), mbstring, openssl, tokenizer, xml, ctype, json, bcmath, gd, zip, curl, fileinfo.
Generate and set APP_KEY before running any Artisan commands or serving the application. Running Doss without an application key means encrypted data (sessions, tokens, user data) cannot be decrypted. Run php artisan key:generate immediately after copying .env.

​
Installation steps

1

Clone the repository

git clone https://github.com/smonderoy/doss.git
cd doss
2

Install PHP dependencies

Install all Composer packages defined in composer.json. Key dependencies include Laravel 10, Laravel Passport, nwidart/laravel-modules, Stripe, Firebase, and Pusher.
composer install --optimize-autoloader --no-dev
For a development environment, omit --no-dev to include packages like PHPUnit, Laravel Pint, and Ignition:
composer install
3

Install JavaScript dependencies

npm install
npm run build
4

Configure environment

Copy the example environment file and open it for editing:
cp .env.example .env
php artisan key:generate
Edit .env and set the values for your environment. See the Environment variables section below for a full reference.At minimum, configure:
.env
APP_NAME=Doss
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=doss
DB_USERNAME=doss_user
DB_PASSWORD=your_database_password

QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
Then install Laravel Passport encryption keys:
php artisan passport:install
5

Run database migrations and seeders

Create the database schema and load required seed data (currencies, countries, transaction types, default settings):
php artisan migrate --seed
The seeder populates essential lookup data including countries, currencies, notification types, transaction types, and a default admin account. Do not skip seeding on a fresh installation.
6

Set file permissions

The web server process must be able to write to the storage and bootstrap/cache directories:
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
Then generate the storage symlink for public file access:
php artisan storage:link
7

Set up queue workers

Doss uses Laravel queues for FCM push notifications, email dispatch, and async transaction processing. Set QUEUE_CONNECTION=redis in .env, then start a worker:
php artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
For production, manage the queue worker with Supervisor so it restarts automatically:
/etc/supervisor/conf.d/doss-worker.conf
[program:doss-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/doss/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/doss/storage/logs/worker.log
stopwaitsecs=3600

supervisorctl reread && supervisorctl update && supervisorctl start doss-worker:*
8

Configure the web server

Point your web server document root to the public/ directory. Below is an example Nginx server block:
/etc/nginx/sites-available/doss
server {
    listen 80;
    server_name your-domain.com;
    root /var/www/doss/public;
    index index.php;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}
Enable the site and reload Nginx:
ln -s /etc/nginx/sites-available/doss /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
For HTTPS, use Certbot to obtain a Let’s Encrypt certificate:
certbot --nginx -d your-domain.com
9

Optimize for production

Cache configuration, routes, and views to improve performance:
php artisan config:cache
php artisan route:cache
php artisan view:cache
To clear all caches (useful during updates):
php artisan optimize:clear

​
Environment variables

The following environment variables control core platform behavior. Set them in your .env file.

​
Application

VariableDescriptionExample
APP_NAMEApplication name shown in emails and notificationsDoss
APP_ENVEnvironment (production, local, staging)production
APP_KEY32-character encryption key — generate with php artisan key:generate
APP_DEBUGShow detailed errors (true only in development)false
APP_URLFull URL of the application including schemehttps://pay.example.com
ADMIN_PREFIXURL prefix for the admin paneladmin
APP_DEMOEnable demo mode (disables destructive actions)false

​
Database

VariableDescriptionDefault
DB_CONNECTIONDatabase driver (mysql or pgsql)mysql
DB_HOSTDatabase server hostname127.0.0.1
DB_PORTDatabase port3306
DB_DATABASEDatabase name
DB_USERNAMEDatabase user
DB_PASSWORDDatabase password

​
Queue and cache

VariableDescriptionDefault
QUEUE_CONNECTIONQueue driver — use redis for productionsync
REDIS_HOSTRedis server hostname127.0.0.1
REDIS_PORTRedis port6379
REDIS_PASSWORDRedis password (if auth is enabled)

​
Broadcasting (Pusher)

Pusher powers real-time in-browser notifications.
VariableDescription
BROADCAST_DRIVERSet to pusher to enable real-time events
PUSHER_APP_IDPusher application ID
PUSHER_APP_KEYPusher application key
PUSHER_APP_SECRETPusher application secret
PUSHER_APP_CLUSTERPusher cluster (e.g., eu, us2)

​
Mail

VariableDescriptionDefault
MAIL_MAILERMail transport (smtp, mailgun, ses, log)smtp
MAIL_HOSTSMTP server hostnamesmtp.mailgun.org
MAIL_PORTSMTP port587
MAIL_ENCRYPTIONEncryption (tls or ssl)tls
MAIL_USERNAMESMTP username
MAIL_PASSWORDSMTP password
MAIL_FROM_ADDRESSSender address
MAIL_FROM_NAMESender display name

​
Payment integrations

Configure only the gateways you intend to activate. Credentials for each gateway are stored in the admin panel under Settings → Payment Methods rather than in .env — the admin UI writes them to the settings database table at runtime.
VariableDescription
STRIPE_KEYStripe publishable key
STRIPE_SECRETStripe secret key

​
Firebase (FCM push notifications)

Firebase credentials are configured via the admin panel. Upload your firebase_credentials.json service account file through Admin → Settings → Firebase. The application uses kreait/firebase-php to send FCM messages to mobile devices.

Build docs developers (and LLMs) love

Get started for freeTalk to us