README

Droplets are integrations between third-party services and Fluid. This is a repository intended to be used as an example for creating Droplets.

Documentation can be found in the project's GitHub page

The Next.js app

This repository now contains two applications against one database.

• The Rails app is everything under app/, config/, db/ and test/. It is live, it owns the schema, and nothing about it has changed.
• The Next.js app lives under src/, with prisma/, scripts/, Dockerfile.next and cloudbuild-next.yml. It maps onto the same Rails tables with @@map and performs no migrations of its own.

Nothing points at the Next app. Fluid calls whatever url is recorded in each installation's callback and webhook registrations, so the Next service takes no traffic until a registration is repointed at it — one company and one callback definition at a time.

Read CUTOVER.md before deploying or repointing anything. It carries the verified local-route → Fluid definition-name mapping for all nine callbacks (three of which differ), the per-route failure policy, and the rollback.

pnpm install
pnpm db:generate          # prisma client
pnpm dev                  # next dev on :3000
pnpm lint / typecheck / test / build
pnpm cutover status <fluid_shop>

The Rails frontend's Vite build moved from yarn to pnpm at the same time, since the root package.json is now the Next app's: pnpm build:vite and pnpm test:jest are the Rails-side scripts.

Production environment

Google cloud infrastructure

• Google Cloud Run (Web)
• Google Cloud Worker (Solidqueue)
• Google Cloud Storage (Terraform)
• Google Cloud SQL (postgreSQL)
• Google Cloud Build (CI/CD)
• Google Cloud Compute Engine (console)
• Artifact Registry (Docker)

web: Google Cloud Run name fluid-droplet-dynamic-pricing solidqueue: Google Cloud worker name fluid-droplet-dynamic-pricing-solidqueue console: Google Cloud Compute Engine name fluid-droplet--dynamic-pricing-console

Deploy to google cloud

Run github action to deploy to google cloud deploy production or run the following command to deploy to google cloud

gcloud beta builds submit --config cloudbuild-production.yml --region=us-west3 --substitutions=COMMIT_SHA=$(git rev-parse --short HEAD),_TIMESTAMP=$(date +%Y%m%d%H%M%S) --project=fluid-417204 .

Add environment variables to google cloud

Add environment variables to google cloud add-update-env-gcloud.sh and run the following command to add environment variables to google cloud sh add-update-env-gcloud.sh

Technology Stack

Local environment

Running locally

Install dependencies with bundle install and yarn install and install foreman with gem install foreman
Just the rails server (port 3000)
foreman start -f Procfile.dev

Running everything (port 3200)
bin/dev

Running locally with Makefile (Docker)

Configure your environment variables in .env file and run the following command:
make install Running it as a docker service (port 3600)
make up

Run make help to see all commands

Running locally with docker

This approach allows you to use your local PostgreSQL instance with Docker.

Prerequisites:

• Docker installed
• PostgreSQL running locally
• Database droplet_template_development created

Step-by-step setup:

1. Copy environment file:

   cp .env.local.example .env

2. Edit .env file with your database credentials:

   # Required
   SECRET_KEY_BASE=your_secret_key_here
   
   # Database connection (use your local PostgreSQL)
   DATABASE_URL=postgresql://username:password@host.docker.internal:5432/droplet_template_development
   
   # Environment
   RAILS_ENV=development

3. Build the Docker image:

   docker build -t droplet-template .

4. Run database migrations (if needed):

   # If you haven't run migrations yet, run them first
   docker run --env-file .env -e RAILS_ENV=development droplet-template bin/rails db:migrate

5. Run the container:

   docker run -p 3200:80 --env-file .env -e RAILS_ENV=development droplet-template

6. Access the application: Open your browser and go to: http://localhost:3200

Notes:

• Use host.docker.internal instead of localhost in DATABASE_URL for Docker to access your local PostgreSQL
• The application will run on port 3200 (mapped from container port 80)
• Make sure your PostgreSQL is running and accessible before starting the container

Running with Docker for development (with Vite and hot reload)

For a full development experience with Vite, TypeScript compilation, and hot reload:

1. Copy environment file:

   cp .env.local.example .env

2. Edit .env file with your database credentials:

   # Required
   SECRET_KEY_BASE=your_secret_key_here
   
   # Database connection (use your local PostgreSQL)
   DATABASE_URL=postgresql://username:password@host.docker.internal:5432/droplet_template_development
   
   # Environment
   RAILS_ENV=development

3. Build the development Docker image:

   docker build -f Dockerfile.dev -t droplet-template-dev .

4. Run the development container:

   docker run -p 3200:3000 -p 3036:3036 --env-file .env -e RAILS_ENV=development droplet-template-dev

5. Access the application:

   • Rails: http://localhost:3200
   • Vite: http://localhost:3036

Development features:

• Hot reload for frontend changes
• TypeScript compilation in watch mode
• Vite dev server for fast frontend development
• Full Rails development environment

License

MIT License

Copyright (c) 2025 Fluid Commerce

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.