75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# 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:
|
|
|
|
```ini
|
|
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/`):
|
|
|
|
1. On your production server, create a directory for persistent data:
|
|
```bash
|
|
mkdir -p /var/www/shared
|
|
```
|
|
2. Move your existing database file there (so you don't lose current users):
|
|
```bash
|
|
mv /var/www/singlelogin/database/database.sqlite /var/www/shared/database.sqlite
|
|
```
|
|
3. Set the correct permissions so the web server can read and write to the database and its parent folder:
|
|
```bash
|
|
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:
|
|
|
|
```ini
|
|
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**:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
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.
|