Skip to main content
This guide covers the complete installation process for self-hosting Minimal, from local development to production deployment.

​
Installation Methods

Choose the installation method that best fits your needs:
  • Local Development: Run Minimal on your local machine for testing and development
  • Production Deployment: Deploy Minimal to a production server or platform
  • Docker: Run Minimal in a containerized environment (coming soon)

​
Local Development Installation

1

Install Runtime

Minimal supports both Bun and Node.js. Choose one:Bun (Recommended)
curl -fsSL https://bun.sh/install | bash
Node.js
# Install Node.js 20+ from https://nodejs.org
# Or use nvm:
nvm install 20
nvm use 20
2

Clone Repository

git clone https://github.com/yourusername/minimal.git
cd minimal
3

Install Dependencies

bun install
4

Configure Environment

Copy the example environment file and configure it:
cp .env.example .env
Minimal configuration for local development:
.env
DATABASE_URL="file:./dev.db"
BETTER_AUTH_SECRET="your-secret-key-here"
NEXT_PUBLIC_APP_URL="http://localhost:3000"
Generate a secure BETTER_AUTH_SECRET with:
openssl rand -base64 32
5

Initialize Database

Generate Prisma client and push schema to database:
bun run db:generate
bun run db:push
This will create a local SQLite database at ./dev.db.
6

Start Development Server

bun run dx
The application will be available at http://localhost:3000.
The dx command is a shortcut that runs install, db:generate, db:push, and dev in sequence.

​
Production Installation

Production deployments require additional security considerations. Always use HTTPS and secure environment variables.

​
Option 1: Platform Deployment (Vercel)

1

Prepare Repository

Ensure your repository is pushed to GitHub, GitLab, or Bitbucket.
2

Deploy to Vercel

  1. Visit vercel.com and sign in
  2. Click “New Project” and import your repository
  3. Configure environment variables (see Configuration)
  4. Deploy
3

Configure Database

For production, use Turso instead of local SQLite:
# Install Turso CLI
curl -sSfL https://get.tur.so/install.sh | bash

# Create database
turso db create minimal-production

# Get connection details
turso db show minimal-production
Add to Vercel environment variables:
  • TURSO_DATABASE_URL
  • TURSO_AUTH_TOKEN
4

Run Migrations

After first deployment, run database migrations:
# Set environment variables locally
export TURSO_DATABASE_URL="your-url"
export TURSO_AUTH_TOKEN="your-token"

# Push schema
bunx prisma db push

​
Option 2: VPS Deployment

1

Prepare Server

Requirements:
  • Ubuntu 22.04+ or similar Linux distribution
  • 2GB+ RAM
  • Node.js 20+ or Bun installed
  • nginx or similar reverse proxy
  • SSL certificate (Let’s Encrypt recommended)
2

Clone and Install

cd /var/www
git clone https://github.com/yourusername/minimal.git
cd minimal
bun install
3

Configure Environment

cp .env.example .env
nano .env
Set production environment variables (see Configuration).
4

Build Application

bun run build
5

Set Up Process Manager

Use PM2 to manage the application:
npm install -g pm2
pm2 start "bun run start" --name minimal
pm2 save
pm2 startup
6

Configure Reverse Proxy

Example nginx configuration:
/etc/nginx/sites-available/minimal
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
Enable site and restart nginx:
ln -s /etc/nginx/sites-available/minimal /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx
7

Set Up SSL

apt install certbot python3-certbot-nginx
certbot --nginx -d your-domain.com

​
Option 3: Docker (Coming Soon)

Docker support is planned for a future release.

​
Database Setup

After installation, you need to set up your database. See the Database Setup guide for detailed instructions on:
  • Local SQLite configuration
  • Turso setup and migration
  • Database backup strategies
  • Schema management

​
Verification

After installation, verify your deployment:
1

Check Application

Visit your application URL and ensure the homepage loads.
2

Test Authentication

Try creating an account to verify authentication is working.
3

Check Database

Verify the database connection:
bun run db:studio
This opens Prisma Studio to view your database.
4

Monitor Logs

Check application logs for errors:
pm2 logs minimal

​
Troubleshooting

​
Build Failures

If the build fails, check:
  1. Node/Bun version: Ensure you’re using Node.js 20+ or latest Bun
  2. Dependencies: Delete node_modules and reinstall
  3. Environment variables: Verify all required variables are set

​
Database Connection Issues

  1. Check URL format: Ensure DATABASE_URL or TURSO_DATABASE_URL is correct
  2. Verify permissions: Ensure the application has write access to SQLite file location
  3. Test connection: Use bun run db:studio to verify database access

​
Runtime Errors

  1. Missing environment variables: Check all required variables are set
  2. Port conflicts: Ensure port 3000 is available or set custom PORT
  3. Memory issues: Increase available RAM for the process

​
Updating

To update your installation: 
# Pull latest changes
git pull origin main

# Install new dependencies
bun install

# Update database schema
bun run db:generate
bun run db:push

# Rebuild application
bun run build

# Restart (PM2)
pm2 restart minimal

# Or redeploy on Vercel
git push
Always backup your database before updating to prevent data loss.

​
Next Steps