Configuration

Learn how to configure Spin for your projects

Configuration File

Configuration is read from the spin.config.json file in your project directory. Here's an example of a Rails application configuration:

{
  "name": "test_rails",
  "version": "1.0.0",
  "type": "rails",
  "repository": {
    "organization": "afomera",
    "name": "test_rails"
  },
  "dependencies": {
    "services": ["sqlite3"],
    "tools": ["ruby", "bundler"]
  },
  "scripts": {
    "setup": {
      "command": "bundle install",
      "description": "Install dependencies",
      "hooks": {
        "pre": {
          "command": "asdf install ruby",
          "description": "Install Ruby version",
          "env": {
            "RUBY_VERSION": "3.2.2"
          }
        },
        "post": {
          "command": "bundle exec rails db:setup",
          "description": "Set up database"
        }
      }
    },
    "test": {
      "command": "bundle exec rspec",
      "description": "Run tests",
      "hooks": {
        "pre": {
          "command": "bundle exec rails db:test:prepare",
          "description": "Prepare test database"
        }
      }
    }
  },
  "env": {
    "development": {}
  },
  "rails": {
    "ruby": {
      "version": "3.4.1"
    },
    "database": {
      "type": "sqlite3",
      "settings": {
        "database": "storage/development.sqlite3"
      }
    },
    "rails": {
      "version": "8.0.1"
    }
  }
}

Scripts Configuration

Scripts are defined in your configuration file under the scripts section. Each script can have:

A main command to execute
A description for documentation
Pre and post hooks with their own commands and environment variables

{
  "scripts": {
    "scriptName": {
      "command": "main command to run",
      "description": "What the script does",
      "hooks": {
        "pre": {
          "command": "run before main command",
          "description": "Setup steps",
          "env": {
            "KEY": "value"
          }
        },
        "post": {
          "command": "run after main command",
          "description": "Cleanup steps"
        }
      }
    }
  }
}

Service Configuration

Services are defined in your configuration file under the framework-specific section (e.g., rails.services). Each service can have:

Docker image and version
Port mappings
Environment variables
Volume mounts
Health checks

{
  "services": {
    "postgres": {
      "type": "docker",
      "image": "postgres:17",
      "port": 5432,
      "environment": {
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres"
      },
      "volumes": {
        "data": "/var/lib/postgresql/data"
      },
      "healthCheck": {
        "command": ["pg_isready", "-U", "postgres"],
        "interval": "10s",
        "timeout": "5s",
        "retries": 3,
        "startPeriod": "10s"
      }
    },
    "redis": {
      "type": "docker",
      "image": "redis:7",
      "port": 6379,
      "volumes": {
        "data": "/data"
      }
    }
  }
}

Procfile.dev

Define additional processes to run alongside your main application:

web: bundle exec rails server -p 3000
worker: bundle exec sidekiq
css: yarn build:css --watch
js: yarn build --watch

Process Types

Each line defines a process type and its command
Process types can be referenced in logs and debugging
All processes are managed together by Spin

Best Practices

Keep sensitive information in .env files
Use version control for spin.config.json
Document service dependencies and requirements
Use health checks for critical services