How to Integrate Lovable with Docker

Docker works with the code files that Lovable generates, so you first need to export your project from Lovable to GitHub. Open your Lovable project in the browser. Click the GitHub icon in the top-right corner. If your project is not already connected, follow the OAuth flow to authorize Lovable with your GitHub account, then click 'Connect project' and choose to create a new repository or link an existing one. Once connected, the GitHub icon turns green, indicating real-time sync is active. Now open your terminal and clone the repository using the HTTPS URL from GitHub: navigate to the repository page, click the green 'Code' button, copy the URL, and run git clone followed by the URL. Once cloned, open the folder in your terminal. You will see the standard Lovable project structure: src/ for React components, supabase/ for Edge Functions, vite.config.ts, tailwind.config.ts, tsconfig.json, and package.json at the root. Confirm that the project builds cleanly before dockerizing: run npm install followed by npm run build and verify that a dist/ folder appears containing index.html and the compiled JavaScript and CSS assets. If the build succeeds locally, it will succeed inside Docker. If it fails, fix the build errors first — they will cause the Docker build to fail at the same step.

Create a file named Dockerfile in the root of your project — the same directory as package.json. The Dockerfile uses a two-stage build pattern: the first stage installs dependencies and compiles the TypeScript/React code into static files, and the second stage copies only those static files into a minimal nginx image. This keeps the final Docker image small by excluding Node.js and all the node_modules from the production image. The build stage uses node:22-alpine (the Alpine Linux variant is much smaller than the default Debian image). It sets the working directory, copies package.json and package-lock.json first (so Docker caches the npm install layer and only re-runs it when dependencies change), installs dependencies with npm ci (cleaner and faster than npm install for CI/CD), then copies the rest of the source code and runs npm run build. The VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY are declared as ARG build arguments — they must be passed at build time because Vite embeds these values into the compiled JavaScript bundle at build time, not at runtime. The nginx stage starts from nginx:alpine, copies the dist/ folder output from the build stage into nginx's web root, and copies a custom nginx.conf that handles single-page application routing (redirecting all paths back to index.html so React Router works correctly). The final image serves the app on port 80.

1# Stage 1: Build
2FROM node:22-alpine AS builder
3
4WORKDIR /app
5
6# Copy package files first for better layer caching
7COPY package.json package-lock.json ./
8RUN npm ci
9
10# Build args for Vite environment variables
11# These are embedded into the bundle at build time
12ARG VITE_SUPABASE_URL
13ARG VITE_SUPABASE_ANON_KEY
14ENV VITE_SUPABASE_URL=$VITE_SUPABASE_URL
15ENV VITE_SUPABASE_ANON_KEY=$VITE_SUPABASE_ANON_KEY
16
17# Copy source and build
18COPY . .
19RUN npm run build
20
21# Stage 2: Serve with nginx
22FROM nginx:alpine
23
24# Copy built files
25COPY --from=builder /app/dist /usr/share/nginx/html
26
27# Copy nginx config for SPA routing
28COPY nginx.conf /etc/nginx/conf.d/default.conf
29
30EXPOSE 80
31
32CMD ["nginx", "-g", "daemon off;"]

React Router uses the HTML5 History API to handle navigation — URLs like /dashboard or /settings are handled client-side by React, not by the server. Without a special nginx configuration, requesting /dashboard directly (or refreshing the page on that route) would return a 404 error because there is no actual file at that path — only the root index.html exists. You need to configure nginx to serve index.html for any path that does not match an existing file. Create a file called nginx.conf in your project root. The configuration defines a server block listening on port 80, sets the root directory to /usr/share/nginx/html where the Vite build output lives, and uses the try_files directive to attempt serving the exact file path first, then fall back to index.html if no file is found. This is the standard SPA routing configuration and is required for any React Router application served statically. The configuration also sets the index file to index.html and enables gzip compression for better performance. The location block for static assets (JavaScript, CSS, images) sets aggressive cache headers since Vite generates content-hashed filenames — the same file content always has the same hash in the filename, so it is safe to cache indefinitely. The main location block sets no-cache headers for index.html itself, ensuring users always get the latest version of the app.

1server {
2    listen 80;
3    server_name _;
4    root /usr/share/nginx/html;
5    index index.html;
6
7    # Enable gzip compression
8    gzip on;
9    gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;
10
11    # Cache static assets with content hashes forever
12    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
13        expires 1y;
14        add_header Cache-Control "public, immutable";
15    }
16
17    # Never cache index.html
18    location = /index.html {
19        add_header Cache-Control "no-cache, no-store, must-revalidate";
20    }
21
22    # SPA routing: serve index.html for all other paths
23    location / {
24        try_files $uri $uri/ /index.html;
25    }
26}

With the Dockerfile and nginx.conf in place, you can now build and test the Docker image on your local machine before deploying to the cloud. Open your terminal in the project root. Build the Docker image by running the docker build command. You need to pass your Supabase credentials as build arguments using the --build-arg flag because Vite embeds them into the compiled JavaScript at build time. Replace the placeholder values with your actual Supabase project URL and anon key — you can find these in Lovable's Cloud tab by clicking the + icon next to Preview, or in your Supabase project settings under Project Settings → API. Give the image a name using the -t flag. The build process runs both stages: the builder stage installs dependencies (this takes one to three minutes the first time) and compiles the TypeScript code, then the nginx stage creates a minimal image with only the compiled output. Once the build succeeds, run the container locally using docker run with port mapping to expose port 80 inside the container as port 8080 on your machine. Open http://localhost:8080 in your browser to verify the app loads and navigation works. Test a direct URL like http://localhost:8080/some-page to confirm the nginx SPA routing is working correctly — you should see the React app, not a 404 page.

1# Build the image (replace with your actual Supabase values)
2docker build \
3  --build-arg VITE_SUPABASE_URL=https://your-project-id.supabase.co \
4  --build-arg VITE_SUPABASE_ANON_KEY=your-anon-key-here \
5  -t my-lovable-app:latest .
6
7# Run the container locally
8docker run -p 8080:80 my-lovable-app:latest
9
10# Or run in background
11docker run -d -p 8080:80 --name lovable-app my-lovable-app:latest

The production Dockerfile builds a static image, but for local development you want hot module replacement — changes to React components should appear in the browser immediately without rebuilding the entire image. Docker Compose solves this by mounting your source code as a volume into a Node.js container running the Vite dev server. Create a docker-compose.yml file in your project root. The configuration defines a service using the node:22-alpine image, mounts the entire project directory as a volume, overrides the default command to run npm run dev, sets the VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY environment variables using your .env.local file, and maps port 5173 from the container to port 5173 on your host machine. Vite's dev server is configured by default to listen on port 5173. After creating this file, create the .env.local file if it does not already exist and add your Supabase credentials. Run docker compose up to start the development server. Docker will pull the node:22-alpine image, install dependencies inside the container, and start the Vite dev server. Open http://localhost:5173 in your browser to see the app running. Changes you make to files in the src/ directory will trigger instant hot module replacement in the browser, just as if you had run npm run dev directly on your machine — except everything runs inside Docker.

1version: '3.8'
2
3services:
4  app:
5    image: node:22-alpine
6    working_dir: /app
7    volumes:
8      - .:/app
9      - /app/node_modules
10    command: sh -c "npm install && npm run dev -- --host"
11    ports:
12      - "5173:5173"
13    env_file:
14      - .env.local
15    environment:
16      - NODE_ENV=development