Production Deployment & Data Persistence Guide

To ensure that user data (and other settings/services) is not lost when you deploy updates to the application, follow these guidelines.

1. Do Not Use SQLite in Ephemeral Environments

By default, the application is configured to use SQLite (database/database.sqlite).

SQLite is a file-based database. In modern hosting environments—such as Heroku, AWS ECS, Docker containers, or digital ocean app platform—the local container storage is ephemeral (destroyed and recreated on every deployment or restart).

Recommended: Switch to a Managed Database (MySQL / PostgreSQL)

For production deployments, change your database connection in your server's .env file to a persistent RDBMS like MySQL or PostgreSQL:

DB_CONNECTION=mysql
DB_HOST=your-production-db-host.com
DB_PORT=3306
DB_DATABASE=singlelogin
DB_USERNAME=admin
DB_PASSWORD=your_secure_password

2. If You Must Use SQLite in Production

If you deploy to a Virtual Private Server (VPS) like DigitalOcean Droplet, Linode, or AWS EC2, or if you use Docker with persistent volumes, you can continue using SQLite securely:

Step A: Move the SQLite Database File to a Shared/Persistent Directory

Do not leave the database.sqlite file inside the deployment root directory (which gets overwritten/cleaned on deployment). Instead, place it in a persistent folder (e.g. /var/www/shared/ or /data/):

On your production server, create a directory for persistent data:
```
mkdir -p /var/www/shared
```

Move your existing database file there (so you don't lose current users):

mv /var/www/singlelogin/database/database.sqlite /var/www/shared/database.sqlite

Set the correct permissions so the web server can read and write to the database and its parent folder:
```
chown -R www-data:www-data /var/www/shared
chmod -R 775 /var/www/shared
```

Step B: Configure the Absolute Path in `.env`

Update the DB_DATABASE environment variable in your production .env file to point to this absolute persistent path:

DB_CONNECTION=sqlite
DB_DATABASE=/var/www/shared/database.sqlite

3. Safe Migration Commands on Deployment

When deploying updates, make sure your deployment scripts run migrations safely:

DO RUN:
```
php artisan migrate --force
```
This command runs only new, pending migration files and keeps all existing data safe. The --force flag allows it to run in production without prompting.
NEVER RUN:
```
php artisan migrate:fresh --seed
```
This command drops all database tables, destroying all registered users and data, and then rebuilds the schema from scratch. Do not use this in production.

4. Git Configurations

The SQLite database file database.sqlite is already ignored in git (database/.gitignore). Do not force-add or commit database files to your git repository, as doing so would cause your local database to overwrite your production database during deployment.

3.0 KiB Raw Blame History