Spry Deployment Strategies: Docker, Cloud Platforms, and CI/CD Pipelines

Deploying applications to production is a critical step in the software development lifecycle. In this comprehensive guide, we'll explore how to deploy Spry – the next‑generation Dart server framework – to various production environments. We'll cover Docker containerization, cloud platforms (AWS, Google Cloud, Azure, Vercel), and CI/CD pipelines for automated deployments.

All code examples are taken from a working Spry project and can be run on your own machine.

1. Why Deployment Matters for Spry Applications

Spry's lightweight architecture and minimal dependencies make it well‑suited for various deployment scenarios. Whether you're deploying a simple API, a full‑stack web application, or a microservice, Spry offers flexibility:

Docker containerization – package your application with all dependencies
Cloud platform deployment – leverage managed services for scalability
CI/CD pipelines – automate testing, building, and deployment
Monitoring and scaling – ensure reliability and performance

In this guide, we'll deploy a complete Spry blog application to multiple platforms and implement a full CI/CD pipeline.

2. Project Setup

Before we begin, let's create a new Spry project with deployment‑related dependencies:

# pubspec.yaml
dependencies:
  spry: ^8.1.0
  dotenv: ^2.0.0          # Environment variables

dev_dependencies:
  test: ^1.25.0           # Testing
  docker: ^3.0.0          # Docker API client (optional)
  googleapis: ^11.0.0     # Google Cloud APIs (optional)
  aws_dart: ^0.5.0        # AWS SDK (optional)

We'll build a simple blog application and deploy it to multiple platforms.

3. Docker Deployment

Docker allows you to package your Spry application with all its dependencies into a portable container.

3.1 Creating a Dockerfile

Create a Dockerfile in your project root:

# Use official Dart image as builder
FROM dart:stable AS builder

# Set working directory
WORKDIR /app

# Copy pubspec files
COPY pubspec.* ./

# Install dependencies
RUN dart pub get

# Copy source code
COPY . .

# Build the application
RUN dart compile exe bin/main.dart -o /app/spry_app

# Create a minimal runtime image
FROM debian:bookworm-slim

# Install runtime dependencies
RUN apt-get update && apt-get install -y \
    ca-certificates \
    tzdata \
    && rm -rf /var/lib/apt/lists/*

# Copy the compiled binary from the builder stage
COPY --from=builder /app/spry_app /app/spry_app

# Create a non-root user
RUN useradd -m -u 1000 spryuser
USER spryuser

# Set working directory
WORKDIR /app

# Expose port (default Spry port is 3000)
EXPOSE 3000

# Start the application
CMD ["/app/spry_app"]

3.2 Docker Compose for Development

Create a docker-compose.yml file for local development with database:

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/spry_blog
      - NODE_ENV=development
    depends_on:
      - db
    volumes:
      - ./logs:/app/logs

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=spry_blog
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

3.3 Building and Running the Container

# Build the Docker image
docker build -t spry-app .

# Run the container
docker run -p 3000:3000 --env-file .env spry-app

# Run with docker-compose
docker-compose up

3.4 Multi‑Stage Build for Smaller Images

Optimize your Dockerfile for production:

# Build stage
FROM dart:stable AS builder

WORKDIR /app
COPY pubspec.* ./
RUN dart pub get

COPY . .
RUN dart compile exe bin/main.dart -o /app/spry_app

# Runtime stage
FROM gcr.io/distroless/base-debian12

# Copy the compiled binary
COPY --from=builder /app/spry_app /app/spry_app

# Run as non-root
USER nobody:nogroup

EXPOSE 3000
CMD ["/app/spry_app"]

This produces an image under 20 MB!

4. Cloud Platform Deployment

Let's deploy our Spry application to popular cloud platforms.

4.1 AWS Elastic Beanstalk

AWS Elastic Beanstalk provides a simple way to deploy web applications.

4.1.1 Configuration Files

Create .ebextensions/spry.config:

option_settings:
  aws:elasticbeanstalk:container:nodejs:
    NodeCommand: "dart run bin/main.dart"
  aws:elasticbeanstalk:application:environment:
    PORT: 8080
    NODE_ENV: production

Create Procfile:

web: dart run bin/main.dart

4.1.2 Deployment Script

Create a deployment script deploy-aws.sh:

#!/bin/bash

# Build the application
dart compile exe bin/main.dart -o spry_app

# Create deployment package
zip -r deploy.zip . -x "*.git*" "*.dart_tool*" "*.idea*" "test*"

# Deploy to Elastic Beanstalk
aws elasticbeanstalk create-application-version \
  --application-name spry-blog \
  --version-label v1.0.0 \
  --source-bundle S3Bucket=my-bucket,S3Key=deploy.zip

aws elasticbeanstalk update-environment \
  --environment-name spry-blog-prod \
  --version-label v1.0.0

4.2 Google Cloud Run

Google Cloud Run is a serverless platform for containerized applications.

4.2.1 Cloud Build Configuration

Create cloudbuild.yaml:

steps:
  # Build the Docker image
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'gcr.io/$PROJECT_ID/spry-app:$COMMIT_SHA', '.']

  # Push the Docker image
  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', 'gcr.io/$PROJECT_ID/spry-app:$COMMIT_SHA']

  # Deploy to Cloud Run
  - name: 'gcr.io/cloud-builders/gcloud'
    args:
      - 'run'
      - 'deploy'
      - 'spry-app'
      - '--image'
      - 'gcr.io/$PROJECT_ID/spry-app:$COMMIT_SHA'
      - '--region'
      - 'us-central1'
      - '--platform'
      - 'managed'
      - '--allow-unauthenticated'

images:
  - 'gcr.io/$PROJECT_ID/spry-app:$COMMIT_SHA'

4.2.2 Dockerfile for Cloud Run

Update your Dockerfile for Cloud Run:

FROM dart:stable AS builder

WORKDIR /app
COPY . .
RUN dart pub get
RUN dart compile exe bin/main.dart -o /app/spry_app

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates tzdata
COPY --from=builder /app/spry_app /app/spry_app

# Cloud Run requires the container to listen on $PORT
ENV PORT=8080
EXPOSE $PORT

CMD ["/app/spry_app"]

Update your Spry application to read the PORT environment variable:

import 'package:spry/spry.dart';
import 'package:dotenv/dotenv.dart';

void main() async {
  final env = DotEnv()..load();
  final port = int.tryParse(env['PORT'] ?? '3000') ?? 3000;

  final spry = Spry();
  // ... configure routes

  await spry.listen(port: port);
  print('Server running on port $port');
}

4.3 Azure App Service

Azure App Service supports custom containers.

4.3.1 Azure Configuration

Create Dockerfile.azure:

FROM dart:stable AS builder
WORKDIR /app
COPY . .
RUN dart pub get
RUN dart compile exe bin/main.dart -o /app/spry_app

FROM mcr.microsoft.com/azure-app-service/base:4.0
COPY --from=builder /app/spry_app /home/site/wwwroot/spry_app

ENV PORT=8080
EXPOSE $PORT

CMD ["/home/site/wwwroot/spry_app"]

Create deploy-azure.sh:

#!/bin/bash

# Login to Azure
az login

# Build and push to Azure Container Registry
az acr build --registry myregistry --image spry-app:latest .

# Deploy to App Service
az webapp config container set \
  --name spry-app \
  --resource-group my-resource-group \
  --docker-custom-image-name myregistry.azurecr.io/spry-app:latest

4.4 Vercel (Serverless Functions)

Vercel supports serverless functions, which we can use with Spry.

4.4.1 Vercel Configuration

Create vercel.json:

{
  "functions": {
    "api/**/*.dart": {
      "runtime": "vercel-dart@latest"
    }
  },
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/api/index.dart"
    }
  ]
}

Create api/index.dart:

import 'package:spry/spry.dart';
import 'package:spry/vercel.dart';

void main() {
  final spry = Spry();

  spry.get('/', (event) => event.response.text('Hello from Vercel!'));

  // Export the handler for Vercel
  exportHandler(spry);
}

Install the Vercel Dart runtime:

npm install -g vercel
vercel dev

5. CI/CD Pipelines

Continuous Integration and Continuous Deployment automate your deployment process.

5.1 GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dart-lang/setup-dart@v1
      - run: dart pub get
      - run: dart test

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dart-lang/setup-dart@v1
      - run: dart pub get
      - run: dart compile exe bin/main.dart -o spry_app
      - uses: actions/upload-artifact@v3
        with:
          name: spry-app
          path: spry_app

  deploy:
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: dart-lang/setup-dart@v1

      # Download the built artifact
      - uses: actions/download-artifact@v3
        with:
          name: spry-app

      # Deploy to your platform (example: SSH)
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            systemctl stop spry-app
            cp spry_app /opt/spry-app/
            systemctl start spry-app

5.2 GitLab CI/CD

Create .gitlab-ci.yml:

stages:
  - test
  - build
  - deploy

test:
  stage: test
  image: dart:stable
  script:
    - dart pub get
    - dart test

build:
  stage: build
  image: dart:stable
  script:
    - dart pub get
    - dart compile exe bin/main.dart -o spry_app
  artifacts:
    paths:
      - spry_app

deploy:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache openssh-client rsync
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
  script:
    - rsync -avz spry_app $DEPLOY_USER@$DEPLOY_HOST:/opt/spry-app/
    - ssh $DEPLOY_USER@$DEPLOY_HOST "systemctl restart spry-app"
  only:
    - main

5.3 Jenkins Pipeline

Create Jenkinsfile:

pipeline {
    agent any

    environment {
        DART_VERSION = 'stable'
    }

    stages {
        stage('Test') {
            steps {
                sh 'dart pub get'
                sh 'dart test'
            }
        }

        stage('Build') {
            steps {
                sh 'dart compile exe bin/main.dart -o spry_app'
                archiveArtifacts artifacts: 'spry_app'
            }
        }

        stage('Deploy') {
            when {
                branch 'main'
            }
            steps {
                sh '''
                    scp spry_app $DEPLOY_USER@$DEPLOY_HOST:/opt/spry-app/
                    ssh $DEPLOY_USER@$DEPLOY_HOST "systemctl restart spry-app"
                '''
            }
        }
    }
}

6. Environment Configuration

Proper environment configuration is essential for deployment.

6.1 Environment Variables

Create a .env.example file:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/spry_blog
REDIS_URL=redis://localhost:6379

# Server
PORT=3000
NODE_ENV=production

# Secrets
JWT_SECRET=your-secret-key
API_KEY=your-api-key

Load environment variables in your Spry application:

import 'package:dotenv/dotenv.dart';

final env = DotEnv()..load();

String get databaseUrl => env['DATABASE_URL'] ?? 'postgresql://localhost:5432/spry_blog';
int get port => int.tryParse(env['PORT'] ?? '3000') ?? 3000;
String get jwtSecret => env['JWT_SECRET'] ?? 'default-secret';

6.2 Configuration Validation

Validate configuration at startup:

class Config {
  final String databaseUrl;
  final int port;
  final String jwtSecret;

  Config.fromEnv(DotEnv env) {
    databaseUrl = env['DATABASE_URL'] ?? 
      throw ConfigurationError('DATABASE_URL is required');

    port = int.tryParse(env['PORT'] ?? '3000') ?? 3000;

    jwtSecret = env['JWT_SECRET'] ?? 
      throw ConfigurationError('JWT_SECRET is required');
  }
}

void main() async {
  final env = DotEnv()..load();
  final config = Config.fromEnv(env);

  final spry = Spry();
  // ... configure with config

  await spry.listen(port: config.port);
}

7. Monitoring and Logging

Production applications need proper monitoring and logging.

7.1 Structured Logging

Implement structured logging:

import 'package:logger/logger.dart';

final logger = Logger(
  printer: PrettyPrinter(),
  level: Level.info,
);

// Use in your routes
spry.get('/articles', (event) async {
  logger.i('Fetching articles', {
    'path': event.request.uri.path,
    'query': event.request.uri.query,
  });

  try {
    final articles = await repository.findAll();
    return event.response.json(articles);
  } catch (e) {
    logger.e('Failed to fetch articles', error: e);
    return event.response.internalServerError();
  }
});

7.2 Health Checks

Implement health check endpoints:

spry.get('/health', (event) async {
  final health = {
    'status': 'healthy',
    'timestamp': DateTime.now().toIso8601String(),
    'uptime': DateTime.now().difference(startTime).inSeconds,
    'services': {},
  };

  // Check database connectivity
  try {
    await db.query('SELECT 1');
    health['services']['database'] = 'healthy';
  } catch (e) {
    health['services']['database'] = 'unhealthy';
    health['status'] = 'degraded';
  }

  // Check Redis connectivity
  try {
    await redis.ping();
    health['services']['redis'] = 'healthy';
  } catch (e) {
    health['services']['redis'] = 'unhealthy';
    health['status'] = 'degraded';
  }

  return event.response.json(health);
});

7.3 Metrics Collection

Collect metrics with Prometheus:

import 'package:prometheus_client/prometheus_client.dart';

final registry = CollectorRegistry();
final requestCounter = Counter(
  'spry_http_requests_total',
  'Total HTTP requests',
  ['method', 'path', 'status'],
  registry: registry,
);

final responseTimeHistogram = Histogram(
  'spry_http_response_time_seconds',
  'HTTP response time in seconds',
  ['method', 'path'],
  registry: registry,
);

// Middleware to collect metrics
Middleware metricsMiddleware() {
  return (Handler handler) {
    return (Event event) async {
      final stopwatch = Stopwatch()..start();

      try {
        final response = await handler(event);
        requestCounter.labels(
          event.request.method,
          event.request.uri.path,
          response.statusCode.toString(),
        ).inc();

        stopwatch.stop();
        responseTimeHistogram
          .labels(event.request.method, event.request.uri.path)
          .observe(stopwatch.elapsedMicroseconds / 1000000);

        return response;
      } catch (e) {
        requestCounter.labels(
          event.request.method,
          event.request.uri.path,
          '500',
        ).inc();
        rethrow;
      }
    };
  };
}

// Expose metrics endpoint
spry.get('/metrics', (event) async {
  final metrics = await registry.collect();
  return event.response.text(metrics, headers: {
    'Content-Type': 'text/plain; version=0.0.4',
  });
});

8. Scaling Strategies

As your Spry application grows, you'll need to scale it.

8.1 Horizontal Scaling with Load Balancers

Deploy multiple instances behind a load balancer:

# nginx configuration
upstream spry_backend {
  least_conn;
  server 10.0.1.1:3000;
  server 10.0.1.2:3000;
  server 10.0.1.3:3000;
}

server {
  listen 80;
  server_name api.example.com;

  location / {
    proxy_pass http://spry_backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

8.2 Database Connection Pooling

Configure database connection pooling for multiple instances:

final pool = Pool<PostgreSQLConnection>(
  create: () async {
    final conn = PostgreSQLConnection(host, port, database);
    await conn.open();
    return conn;
  },
  dispose: (conn) => conn.close(),
  validate: (conn) => conn.isClosed ? false : true,
  max: 20,  // Maximum connections per instance
);

8.3 Session Management with Redis

Use Redis for distributed session storage:

class RedisSessionStore implements SessionStore {
  final RedisConnection redis;

  @override
  Future<String?> get(String sessionId) async {
    return await redis.get('session:$sessionId');
  }

  @override
  Future<void> set(String sessionId, String data, Duration ttl) async {
    await redis.set('session:$sessionId', data);
    await redis.expire('session:$sessionId', ttl.inSeconds);
  }
}

9. Security Best Practices

Secure your deployed Spry applications:

9.1 HTTPS Configuration

Always use HTTPS in production:

import 'dart:io';

void main() async {
  final spry = Spry();

  // ... configure routes

  final sslContext = SecurityContext()
    ..useCertificateChain('path/to/cert.pem')
    ..usePrivateKey('path/to/key.pem');

  await spry.listen(
    port: 443,
    securityContext: sslContext,
  );
}

9.2 Security Headers

Add security headers middleware:

Middleware securityHeaders() {
  return (Handler handler) {
    return (Event event) async {
      final response = await handler(event);

      response.headers.addAll({
        'X-Content-Type-Options': 'nosniff',
        'X-Frame-Options': 'DENY',
        'X-XSS-Protection': '1; mode=block',
        'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
        'Content-Security-Policy': "default-src 'self'",
      });

      return response;
    };
  };
}

9.3 Rate Limiting

Implement rate limiting:

import 'package:rate_limit/rate_limit.dart';

final limiter = RateLimiter(
  maxRequests: 100,
  window: Duration(minutes: 1),
);

Middleware rateLimitMiddleware() {
  return (Handler handler) {
    return (Event event) async {
      final ip = event.request.headers['x-forwarded-for'] ?? 
                 event.request.connectionInfo?.remoteAddress?.address ?? 
                 'unknown';

      if (!limiter.allow(ip)) {
        return Response.tooManyRequests('Rate limit exceeded');
      }

      return handler(event);
    };
  };
}

10. Zero‑Downtime Deployments

Implement zero‑downtime deployment strategies:

10.1 Blue‑Green Deployment

#!/bin/bash
# blue-green-deploy.sh

# Deploy new version (green)
docker-compose -f docker-compose-green.yml up -d

# Wait for health check
sleep 30
curl -f http://green.example.com/health || exit 1

# Switch traffic (update load balancer)
aws elbv2 modify-listener --listener-arn $LISTENER_ARN \
  --default-actions Type=forward,TargetGroupArn=$GREEN_TARGET_ARN

# Wait for old connections to drain
sleep 60

# Stop old version (blue)
docker-compose -f docker-compose-blue.yml down

10.2 Canary Deployment

// Middleware for canary testing
Middleware canaryMiddleware(double percentage) {
  return (Handler handler) {
    return (Event event) async {
      final userId = event.context['user']?['id'];
      final isCanary = userId != null && userId % 100 < (percentage * 100);

      if (isCanary) {
        // Route to canary version
        event.context['version'] = 'canary';
      } else {
        event.context['version'] = 'stable';
      }

      return handler(event);
    };
  };
}

11. Complete Example: Production‑Ready Spry Application

Let's deploy a complete Spry application with all best practices:

import 'package:spry/spry.dart';
import 'package:dotenv/dotenv.dart';
import 'package:logger/logger.dart';
import 'package:prometheus_client/prometheus_client.dart';

void main() async {
  // Load configuration
  final env = DotEnv()..load();
  final config = Config.fromEnv(env);

  // Initialize logging
  final logger = Logger(level: config.logLevel);

  // Initialize metrics
  final registry = CollectorRegistry();
  final metrics = Metrics(registry);

  // Create Spry instance
  final spry = Spry();

  // Apply middleware
  spry.use(securityHeaders());
  spry.use(rateLimitMiddleware());
  spry.use(metrics.middleware());
  spry.use(loggingMiddleware(logger));
  spry.use(databaseMiddleware(config.databaseUrl));

  // Routes
  spry.get('/', (event) => event.response.text('Welcome to Spry!'));
  spry.get('/health', healthCheck);
  spry.get('/metrics', metrics.handler);

  // API routes
  spry.use('/api', requireAuth());
  spry.get('/api/articles', getArticles);
  spry.post('/api/articles', createArticle);

  // Start server
  final server = await spry.listen(
    port: config.port,
    securityContext: config.sslContext,
  );

  logger.i('Server started on port ${config.port}');

  // Graceful shutdown
  ProcessSignal.sigterm.watch().listen((_) async {
    logger.i('Shutting down gracefully...');
    await server.close();
    await database.close();
    logger.i('Shutdown complete');
    exit(0);
  });
}

12. Conclusion

Deploying Spry applications to production requires careful planning and the right tools. By following the strategies outlined in this guide, you can deploy your Spry applications with confidence, whether you're using Docker, cloud platforms, or implementing full CI/CD pipelines.

Key takeaways:

Docker provides consistent environments across development and production
Cloud platforms offer managed services for scalability and reliability
CI/CD pipelines automate testing, building, and deployment
Monitoring and logging are essential for production applications
Security must be baked into your deployment strategy

All code examples are available in the companion GitHub repository: [link to your repo].

Next steps:

Explore Kubernetes for advanced container orchestration
Learn about service mesh (Istio, Linkerd) for microservices
Implement advanced monitoring with Grafana and Alertmanager
Set up disaster recovery and backup strategies

Happy deploying with Spry! 🚀

Command Palette