Deployment

Summary: This section presents the various ways to deploy a StartER application, in both development and production environments.

Isomorphic architecture

StartER is based on an isomorphic architecture (integrated frontend and backend), which simplifies configuration: a single command allows you to build and launch the entire project.

Implementation in StartER

Local environment

Development mode

In development mode, the server is launched with Vite configured in middleware mode. This provides hot reloading, dynamic server-side rendering (SSR), and on-the-fly compilation.

First, initialize your local database if you haven't already:

npm run database:sync

Then, launch the server:

npm run dev

The Express server is then accessible at: http://localhost:5173. This mode uses raw sources (TypeScript, JSX...) without going through a build process.

Local production mode

To simulate a production environment without Docker, run the build sequence and then execute the compiled server:

npm run build
npm start

The npm run build command executes in succession:

• vite build --outDir dist/client to compile the client part (frontend)
• vite build --outDir dist/server --ssr src/entry-server to compile the server part (SSR)

When NODE_ENV=production is set in the environment variables, the Express server (server.ts) automatically detects the production mode and:

• enables HTTP response compression
• serves precompiled static files from dist/client
• uses server rendering from dist/server/entry-server

Using Docker Compose

StartER adopts a "Zero-Config" approach. Docker is not necessary to run the database (SQLite), but it is still provided for optional tools like Mailpit.

Development environment

In development, Docker only launches the following service if you wish:

• mailpit: a dummy SMTP server to intercept and visualize emails sent by the application.

To start Mailpit:

docker compose up --build

The Mailpit interface will be accessible at http://localhost:8025.

Production environment

For a containerized production deployment, StartER provides a compose.prod.yaml file. The server container builds the project inside the image before launching it.

To deploy in production:

docker compose -f compose.prod.yaml up --build

The client and server builds will be generated in dist/, and the Express server will directly serve the optimized files.

Database and persistence

Since StartER uses SQLite, the database is a simple file located in data/sqlite/database.sqlite.

To keep your data when deploying with Docker, you must use a volume that points to the data directory:

# Simplified example of compose.prod.yaml
services:
  server:
    # ... server configuration ...
    volumes:
      - ./data/sqlite:/app/data/sqlite

This way, even if you recreate the container, the SQLite file will remain intact on your host machine.

Environment variables

The variables required for StartER to function are defined in the .env file. Unlike traditional relational database systems (MySQL, Postgres...), there are no network connection variables to configure for SQLite.

# .env - Environment Variables Configuration

# The base URL where your application is accessible (used for magic links)
APP_BASE_URL=http://localhost:5173

# The port on which the Express server will listen (default: 5173)
APP_PORT=5173

# Secret key used for signing JWTs and other security features.
# TIP: You can use `openssl rand -hex 32` to generate a secure random key.
APP_SECRET=YOUR_APP_SECRET_KEY

# The SMTP connection URL used by the application to send emails.
SMTP_URL=smtps://username:password@smtp.example.com/?pool=true

Deployment with Caddy

Caddy is an excellent reverse proxy that automatically manages HTTPS certificates. It makes your StartER application accessible on the web very easily.

Configuration Example (Caddyfile)

my-domain.com {
  reverse_proxy localhost:5173
}

1. Launch StartER (via Docker or npm start).
2. Launch Caddy with this configuration.
3. Your application is available in HTTPS at https://my-domain.com.

Best practices and use cases

• Never commit the .env file or the database.sqlite file (they are excluded by default in the .gitignore).
• In production, always use a strong and unique APP_SECRET key.
• Ensure that the src/database/data folder has write permissions for the user who launches the server.

See also

• One server
• Installation