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

Production environment

Google cloud infrastructure

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

web: Google Cloud Run name fluid-droplet-NAME

jobs console: Google Cloud Compute Engine name fluid-droplet-NAME-jobs-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

Sentry Configuration

This project includes Sentry integration for error monitoring and performance tracking. To enable Sentry:

1. Create a Sentry project:

   • Go to Sentry.io and create a new project
   • Select "Ruby" as the platform
   • Copy the DSN from your project settings

2. Set the environment variable:

   • Add SENTRY_DSN to your environment variables with the DSN from your Sentry project
   • For local development, add it to your .env file:

     SENTRY_DSN=https://your-dsn@sentry.io/project-id

   • For production, add it to your Google Cloud environment variables

3. Sentry features enabled:

   • Automatic error tracking and reporting
   • Performance monitoring
   • Request headers and IP data collection (for debugging)
   • Active Support and HTTP logger breadcrumbs

The Sentry integration will only be active when the SENTRY_DSN environment variable is present and configured.

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 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.