Jump to heading Scotty mPaaS Integration

Phabalicious provides comprehensive integration with the Scotty mPaaS (micro Platform as a Service) platform, allowing you to deploy and manage Docker-based applications through Scotty's REST API.

Jump to heading Overview

Scotty is a lightweight platform for managing Docker-based applications with features like:

Automatic app discovery and lifecycle management
Load balancer integration (Traefik/HAProxy)
SSL certificate management
Blueprint-based deployments
Environment variable management
Custom domain support

Jump to heading Requirements

To use Scotty integration, you need:

A running Scotty server
Access token for authentication
scottyctl CLI tool installed and accessible

Jump to heading Basic Configuration

Add scotty to your needs section and configure the connection:

needs:
  - scotty

scotty:
  server: https://scotty.example.com
  access-token: your-access-token

Jump to heading Configuration Reference

Jump to heading Required Configuration

Option	Description	Example
`server`	Scotty server URL	`https://scotty.example.com`
`access-token`	Authentication token	`your-secret-token`

Jump to heading Optional Configuration

Option	Description	Default	Example
`app-name`	Application name	`%host.configName%`	`my-app`
`app-blueprint`	Deployment blueprint	-	`nginx-lagoon`
`basic-auth`	HTTP basic authentication	-	See below
`registry`	Docker registry name	-	`factorial`
`ttl`	App time-to-live	-	`1h`, `forever`
`allow-robots`	Allow robot indexing	`false`	`true`
`destroy-on-ttl`	Auto-destroy after TTL	`false`	`true`
`env-file`	Environment variables file	-	`.env.scotty`
`services`	Service port mappings	-	See below
`environment`	Environment variables	-	See below
`custom-domains`	Custom domain mappings	-	See below
`middleware`	Traefik middleware	-	See below
`scaffold`	File/asset configuration	-	See below

Jump to heading Basic Authentication

scotty:
  basic-auth:
    username: admin
    password: secret

Jump to heading Service Configuration

Map public container services to ports, every service is accessible via a autogenerated domain or a custom domain (see below). Your app can consist of more services, declare here only the public ones which should be reachable from the internet.

scotty:
  services:
    nginx: 80
    api: 3000
    websocket: 8080

Jump to heading Environment Variables

Set environment variables for your application. You can use the phabs way to handle secrets:

scotty:
  environment:
    APP_ENV: production
    DATABASE_URL: "%host.secrets.DATABASE_URL%"
    API_KEY: "%host.secrets.API_KEY%"

Jump to heading Custom Domains

Map custom domains to services:

scotty:
  custom-domains:
    api.example.com: api
    www.example.com: nginx

Jump to heading Environment File Loading

Load environment variables from a file:

scotty:
  env-file: .env.production
  # Variables from file are merged with environment config
  environment:
    APP_ENV: production

The environment file should contain variables in KEY=VALUE format:

DATABASE_URL=mysql://user:pass@host:3306/db
API_KEY=your-secret-key
DEBUG=false

Jump to heading Middleware Configuration

Configure Traefik middleware for advanced routing:

scotty:
  middleware:
    - auth@file
    - rate-limit@docker
    - compress

Middleware can be specified as:

Simple strings: compress
Named middleware: auth@file
Array format for multiple middleware

Jump to heading Automatic Cleanup

Configure automatic app destruction after TTL expires:

scotty:
  ttl: 2h
  destroy-on-ttl: true

This is useful for temporary deployments, review apps, or testing environments.

Jump to heading Scaffold Configuration

Configure file and asset copying:

scotty:
  scaffold:
    assets:
      - ./docker-compose.yml
      - ./nginx.conf
    public:
      - ./public/index.html
    scaffold:
      - copy_assets(%rootFolder%)
      - copy_assets(%rootFolder%/public, public)

Jump to heading Deployment Workflows

Jump to heading Creating a New Application

Use the deploy command to create and deploy your application:

phab --config=production deploy

This will:

Scaffold the application files
Create the app in Scotty
Start the application services

Jump to heading Checking Application Status

phab --config=production app:check-existing

Jump to heading Destroying an Application

phab --config=production app:destroy

Jump to heading Complete Example Configuration

name: my-web-app

needs:
  - local
  - scotty

executables:
  scottyctl: /usr/local/bin/scottyctl

scotty:
  server: https://scotty.example.com
  access-token: "%secrets.SCOTTY_TOKEN%"
  app-blueprint: nginx-lagoon
  basic-auth:
    username: admin
    password: "%secrets.BASIC_AUTH_PASSWORD%"
  registry: myregistry
  ttl: 24h
  allow-robots: false
  destroy-on-ttl: false
  env-file: .env.production
  services:
    nginx: 80
    api: 3000
  environment:
    APP_ENV: production
    DATABASE_URL: "%host.secrets.DATABASE_URL%"
    REDIS_URL: "%host.secrets.REDIS_URL%"
  custom-domains:
    www.example.com: nginx
    api.example.com: api
  middleware:
    - auth@file
    - rate-limit
  scaffold:
    docker:
      - ./docker-compose.yml
      - ./Dockerfile
    config:
      - ./nginx.conf
      - ./app.env
    public:
      - ./public/index.html
      - ./public/assets/*
    scaffold:
      - copy_assets(%rootFolder%)
      - copy_assets(%rootFolder%/public, public)
      - copy_assets(%rootFolder%/config, config)

hosts:
  production:
    needs:
      - scotty
    scotty:
      app-name: my-web-app-prod
      environment:
        APP_ENV: production

  staging:
    inheritsFrom: production
    scotty:
      app-name: my-web-app-staging
      server: https://scotty-staging.example.com
      ttl: 7d
      destroy-on-ttl: true
      environment:
        APP_ENV: staging

Jump to heading Blueprint Usage

Scotty supports blueprints for standardized deployments. Configure a blueprint:

scotty:
  app-blueprint: nginx-lagoon

Common blueprints include:

nginx-lagoon: NGINX with Lagoon compatibility
drupal-lagoon: Drupal with Lagoon stack

You can list available blueprints using the scottyctl blueprint:list command.

Jump to heading Environment Variable Patterns

Jump to heading Using Secrets

scotty:
  environment:
    # Reference host secrets
    DATABASE_PASSWORD: "%host.secrets.DB_PASSWORD%"

    # Reference global secrets
    API_KEY: "%secrets.THIRD_PARTY_API_KEY%"

    # Mix static and dynamic values
    DATABASE_URL: "mysql://user:%host.secrets.DB_PASSWORD%@db:3306/app"

Jump to heading Conditional Environment Variables

hosts:
  production:
    scotty:
      environment:
        APP_ENV: production
        DEBUG: "false"

  development:
    scotty:
      environment:
        APP_ENV: development
        DEBUG: "true"
        LOG_LEVEL: debug

Jump to heading Advanced Configuration

Jump to heading Multiple Services

For complex applications with multiple services:

scotty:
  services:
    web: 80
    api: 3000
    websocket: 8080
    admin: 8000
  custom-domains:
    www.example.com: web
    api.example.com: api
    ws.example.com: websocket
    admin.example.com: admin

Jump to heading Time-based Deployments

Set TTL for temporary deployments:

scotty:
  ttl: 2h      # 2 hours
  ttl: 7d      # 7 days
  ttl: forever # Permanent

Jump to heading Registry Configuration

Use private Docker registries:

scotty:
  registry: mycompany
  # Assumes registry is configured in Scotty server

Jump to heading Troubleshooting

Jump to heading Common Issues

Connection Failed

Error: Failed to connect to Scotty server

Verify server URL is correct and accessible
Check access token is valid
Ensure network connectivity

App Creation Failed

Error: Failed to run scottyctl create

Check required scaffold files exist
Verify service port mappings
Review Scotty server logs for details

Authentication Issues

Error: Unauthorized access

Verify access token is correct
Check token hasn't expired
Ensure token has required permissions

Jump to heading Debug Mode

Enable verbose output:

phab --config=production deploy -vvv

Jump to heading Checking Configuration

Verify your Scotty configuration:

phab --config=production about

Jump to heading Migration from Manual Deployments

If migrating from manual Scotty deployments:

Inventory existing apps: List current applications
Extract configuration: Document current service mappings
Create fabfile: Build Phabalicious configuration
Test deployment: Deploy to staging first
Adopt existing: Use app:adopt if needed

Jump to heading Security Considerations

Store access tokens in secrets, not configuration files
Use environment-specific access tokens
Configure appropriate TTL values for temporary deployments
Enable basic authentication for sensitive applications
Use custom domains for production applications

Jump to heading # Scotty mPaaS Integration

Jump to heading # Overview

Jump to heading # Requirements

Jump to heading # Basic Configuration

Jump to heading # Configuration Reference

Jump to heading # Required Configuration

Jump to heading # Optional Configuration

Jump to heading # Basic Authentication

Jump to heading # Service Configuration

Jump to heading # Environment Variables

Jump to heading # Custom Domains

Jump to heading # Environment File Loading

Jump to heading # Middleware Configuration

Jump to heading # Automatic Cleanup

Jump to heading # Scaffold Configuration

Jump to heading # Deployment Workflows

Jump to heading # Creating a New Application

Jump to heading # Checking Application Status

Jump to heading # Destroying an Application

Jump to heading # Complete Example Configuration

Jump to heading # Blueprint Usage

Jump to heading # Environment Variable Patterns

Jump to heading # Using Secrets

Jump to heading # Conditional Environment Variables

Jump to heading # Advanced Configuration

Jump to heading # Multiple Services

Jump to heading # Time-based Deployments

Jump to heading # Registry Configuration

Jump to heading # Troubleshooting

Jump to heading # Common Issues

Jump to heading # Debug Mode

Jump to heading # Checking Configuration

Jump to heading # Migration from Manual Deployments

Jump to heading # Security Considerations

Jump to heading # Related Documentation