From 94e476c981920e9d8c3bc840d5f30f38a4763cd0 Mon Sep 17 00:00:00 2001 From: Lasim Date: Sun, 13 Apr 2025 20:50:10 +0200 Subject: [PATCH] feat(docs): enhance service connection documentation with new mappings structure and examples --- docs/deploystack/deploystack-config-file.md | 10 +++-- docs/docker-to-iac/api.md | 10 ++++- docs/docker-to-iac/service-connections.md | 46 ++++++++++++++++++--- 3 files changed, 57 insertions(+), 9 deletions(-) diff --git a/docs/deploystack/deploystack-config-file.md b/docs/deploystack/deploystack-config-file.md index 87dace2..733b264 100644 --- a/docs/deploystack/deploystack-config-file.md +++ b/docs/deploystack/deploystack-config-file.md @@ -43,9 +43,11 @@ You can override these values using the `config.yml` (only on your main branch) | Property | Type | Description | Constraints | |----------|------|-------------|-------------| -| `name` | String | Override the repository name for DeployStack display | Maximum 40 characters | -| `description` | String | Override the repository description for DeployStack display | Maximum 500 characters | -| `logo` | String | URL to your application logo | [Application Logo Configuration](/docs/deploystack/application-logo-configuration.md) | +| `mappings` | Array | Defines relationships between services for connection configuration | Required | +| `mappings[].fromService` | String | Service that needs to connect to another service | Required | +| `mappings[].toService` | String | Service being connected to | Required | +| `mappings[].environmentVariables` | Array of Strings | Environment variable names that reference the target service | Required | +| `mappings[].property` | String | Type of connection property to reference (e.g., 'connectionString', 'hostport') | Optional, defaults to 'hostport' | The override process follows this order: @@ -148,10 +150,12 @@ deployment: environmentVariables: - "DATABASE_HOST" - "DATABASE_URL" + property: "connectionString" - fromService: "frontend" toService: "api" environmentVariables: - "API_URL" + property: "hostport" ``` This configuration tells DeployStack how to properly configure communication between: diff --git a/docs/docker-to-iac/api.md b/docs/docker-to-iac/api.md index 8d1aec3..be8282e 100644 --- a/docs/docker-to-iac/api.md +++ b/docs/docker-to-iac/api.md @@ -426,6 +426,7 @@ type ServiceConnectionsConfig = { fromService: string; // Service that needs to connect toService: string; // Service to connect to environmentVariables: string[]; // Environment variables that reference the service + property?: string; // Connection property type (connectionString, hostport, etc.) }> }; ``` @@ -443,7 +444,14 @@ serviceConnections: { { fromService: 'frontend', toService: 'api', - environmentVariables: ['API_URL'] + environmentVariables: ['API_URL'], + property: 'hostport' + }, + { + fromService: 'app', + toService: 'db', + environmentVariables: ['DATABASE_URL'], + property: 'connectionString' } ] } diff --git a/docs/docker-to-iac/service-connections.md b/docs/docker-to-iac/service-connections.md index b91adb5..118dba7 100644 --- a/docs/docker-to-iac/service-connections.md +++ b/docs/docker-to-iac/service-connections.md @@ -5,7 +5,7 @@ menuTitle: Service Connections # Service Connections -The `docker-to-iac` module now supports configuring service-to-service communication when translating Docker Compose files to cloud provider IaC templates. This feature is essential for multi-container applications where services need to communicate with each other (e.g., web applications connecting to databases). +The `docker-to-iac` module supports configuring service-to-service communication when translating Docker Compose files to cloud provider IaC templates. This feature is essential for multi-container applications where services need to communicate with each other (e.g., web applications connecting to databases). ## The Challenge @@ -63,7 +63,8 @@ const result = translate(dockerComposeContent, { environmentVariables: [ // List of env vars that reference the service 'DATABASE_HOST', 'API_URL' - ] + ], + property: 'connectionString' // The type of connection (connectionString, hostport, etc.) } ] } @@ -77,6 +78,7 @@ For each service connection mapping: - `fromService`: The service that needs to connect to another service - `toService`: The service being connected to - `environmentVariables`: Array of environment variable names that reference the target service +- `property`: The type of connection property to reference (e.g., 'connectionString', 'hostport', etc.) ## Provider-Specific Implementations @@ -99,7 +101,7 @@ services: fromService: name: db type: pserv - property: hostport + property: hostport # This property is derived from the 'property' parameter in your mapping ``` This approach leverages Render's built-in service discovery capabilities for reliable inter-service communication. @@ -122,7 +124,7 @@ services: ## Complete Example -Here's a complete example showing Node.js microservices communicating with each other: +Here's a complete example showing Node.js microservices communicating with each other, and a more detailed database connection example: ```javascript const dockerComposeContent = ` @@ -148,13 +150,47 @@ const serviceConnections = { { fromService: 'frontend', toService: 'api', - environmentVariables: ['API_URL'] + environmentVariables: ['API_URL'], + property: 'hostport' } ] }; // For DigitalOcean - Service name stays as "api" in http://api:3000 // For Render - Will use fromService syntax instead of string replacement + +// Database Connection Example +const databaseComposeContent = ` +services: + app: + image: node:18-alpine + environment: + - DATABASE_URL=postgresql://postgres:secret@postgres:5432/mydb + ports: + - "3000:3000" + + postgres: + image: postgres:latest + environment: + - POSTGRES_DB: mydb + - POSTGRES_USER: postgres + - POSTGRES_PASSWORD: secret +`; + +const dbServiceConnections = { + mappings: [ + { + fromService: 'app', + toService: 'postgres', + environmentVariables: ['DATABASE_URL'], + property: 'connectionString' // Use connectionString for full database URL + } + ] +}; + +// Result will include proper connection format for each provider +// DigitalOcean: DATABASE_URL=${postgres.DATABASE_URL} +// Render: fromDatabase: { name: "postgres", property: "connectionString" } ``` ## Response Format