Deployment en US - rocambille/start-express-react GitHub Wiki

This section presents the different ways to deploy a StartER application, in a development or production environment. StartER is based on an isomorphic architecture (integrated frontend and backend), which simplifies configuration: a single command can build and launch the entire project.

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

npm run dev

The Express server is then accessible at the address:

http://localhost:5173

This mode uses raw sources (TypeScript, JSX...) without going through a build process.

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

npm run build
npm start

The npm run build command successively executes:

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

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

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

StartER includes a ready-to-use Docker configuration, compatible with MySQL and Adminer. Two files are provided: compose.yaml for development and compose.prod.yaml for production.

Development mode launches the following services:

• server: the Express + Vite server
• database: a persistent MySQL instance
• adminer: a web interface for the database

To start the full environment:

docker compose up --build

The application will be accessible at http://localhost:5173, and Adminer at http://localhost:8080.

The compose.prod.yaml file replicates the development configuration, but with:

• the NODE_ENV=production environment variable

• a custom startup command:

  sh -c "npm run build && npm start"

This builds the project inside the container before launching it.

To deploy to production:

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

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

The MySQL database configuration is defined in compose.yaml:

database:
image: mysql:lts
restart: always
env_file: ./.env
volumes:
- "./src/database/schema.sql:/docker-entrypoint-initdb.d/schema.sql"
- "./src/database/data:/var/lib/mysql"

On first launch, the schema.sql file is executed to initialize the database. The data is then stored in the src/database/data volume to persist between reboots.

Adminer is accessible in development mode at the following address:

http://localhost:8080

The variables required for StartER to function are defined in the .env file. For example:

APP_PORT=5173
APP_SECRET=my_secret
MYSQL_ROOT_PASSWORD=123456
MYSQL_DATABASE=starter

The .env file is automatically read by npm scripts and Docker services (env_file: ./.env).

Caddy is a powerful and extensible platform for serving websites, services, and web applications. It automatically manages HTTPS certificates and offers a very easy to configure reverse proxy. This is a right add-on to finalize the deployment of your StartER application on a server machine.

Caddy uses a fairly accessible configuration format: the Caddyfile. A typical configuration for StartER might look like this:

example.com {
    encode zstd gzip

    reverse_proxy localhost:5173 {
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }

    log {
        output file /var/log/caddy/example.log
        format single_field common_log
    }
}

• reverse_proxy localhost:5173 redirects all incoming traffic to StartER's Node server (port 5173 by default).
• encode zstd gzip enables HTTP compression on the Caddy side.
• log stores request logs in a local file.
• HTTPS is configured automatically (no manual certificate management is required).

1. Build and start StartER in production mode:

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

2. Launch Caddy with the configuration file:

sudo caddy run --config /path/to/your/Caddyfile

The application will then be available at the configured address (https://example.com).

• Do not include the .env file in the Git repository.
• In production, use a different secret key (APP_SECRET) than the one used in development.
• Always run npm run build before deploying if not using Docker.
• If you're using Caddy, let it handle TLS and proxy headers: no SSL configuration is required in Express.