Creating Solutions

This guide walks you through creating solutions that bundle sequences for deployment across environments.

Before You Begin

Make sure you have:

• At least one published sequence to include
• Understanding of your deployment pipeline
• Environments configured in your system

Creating a Solution

Step 1: Navigate to Solutions

1. Open Lens in your browser
2. Open the Deployment group in the top navigation, then the Solutions pill
3. Click New Solution

Step 2: Basic Information

Field	Description	Example
Name	Unique identifier	customer-portal
Initial Version	Starting version	1.0.0

Step 3: Add Sequences

There is no dialog. Clicking Add Sequence appends a blank row to the list, which you then fill in place:

1. Click Add Sequence
2. Pick the sequence from the dropdown in the new row
3. Set the version requirement in the same row (prefilled ^1.0.0)

┌─────────────────────────────────────────────────────────┐
│  Sequences                              [+ Add Sequence]│
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. [deploy-backend         ▼]  [^1.0.0    ]  [↑][↓][✕] │
│  2. [                       ▼]  [^1.0.0    ]  [↑][↓][✕] │
│                                                         │
└─────────────────────────────────────────────────────────┘

Step 4: Order Sequences

Sequences execute in order. Arrange appropriately:

┌─────────────────────────────────────────────────────────┐
│  Solution Sequences                                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. [≡] run-migrations (^1.0.0)         [↑] [↓] [✕]    │
│  2. [≡] deploy-backend (^2.0.0)         [↑] [↓] [✕]    │
│  3. [≡] deploy-frontend (^1.0.0)        [↑] [↓] [✕]    │
│  4. [≡] warmup-caches (^1.0.0)          [↑] [↓] [✕]    │
│                                                         │
│  [+ Add Sequence]                                       │
│                                                         │
└─────────────────────────────────────────────────────────┘

Step 5: Create the Solution

Click Create Solution to save. You will be redirected to the solution detail page.

Step 6: Configure Variable Templates (Optional)

Variables that differ per environment are defined through the Variable Sets UI (or the variables API), not on the solution page — the solution header action bar is only Promote / Edit / Delete, and there is no “Variable Templates” button. Create the variable in a variable set, then link that set to the solution with POST /api/v1/solutions/{solution_id}/variable-sets. scope_solution_id is a read-only column, not a request field — CreateVariableRequest is deny_unknown_fields and does not declare it. scope_environment_id IS a real request field and is how per-environment values are scoped.

Solution Editor Interface

The create form has two cards — Basic Information and Sequences — followed by the action bar.

┌─────────────────────────────────────────────────────────┐
│  Create Solution                                        │
├─────────────────────────────────────────────────────────┤
│  Basic Information                                      │
│  ─────────────────────────────────────────────────────  │
│  Name:    [customer-portal                      ]       │
│  Version: [1.0.0                                ]       │
├─────────────────────────────────────────────────────────┤
│  Sequences                                              │
│  ─────────────────────────────────────────────────────  │
│  ┌─────┬─────────────────────┬────────────┬─────────┐   │
│  │ #   │ Sequence            │ Version    │ Actions │   │
│  ├─────┼─────────────────────┼────────────┼─────────┤   │
│  │ 1   │ run-migrations      │ ^1.0.0     │ [↑][↓][✕]│  │
│  │ 2   │ deploy-backend      │ ^2.0.0     │ [↑][↓][✕]│  │
│  │ 3   │ deploy-frontend     │ ^1.0.0     │ [↑][↓][✕]│  │
│  └─────┴─────────────────────┴────────────┴─────────┘   │
│                                                         │
│  [+ Add Sequence]                                       │
│                                                         │
│                     [Cancel]  [Create Solution]         │
└─────────────────────────────────────────────────────────┘

Example Solutions

Web Application

Sequence	Version	Purpose
database-migration	^1.0.0	Update database schema
deploy-api	^2.0.0	Deploy API services
deploy-web	^1.0.0	Deploy web frontend
invalidate-cdn	^1.0.0	Clear CDN cache

Microservices Suite

Sequence	Version	Purpose
deploy-gateway	^1.0.0	API Gateway
deploy-auth-service	^1.0.0	Authentication service
deploy-user-service	^2.0.0	User management
deploy-order-service	^1.0.0	Order processing
health-check-all	^1.0.0	Verify all services

Infrastructure Update

Sequence	Version	Purpose
backup-configs	^1.0.0	Save current configs
update-certificates	^1.0.0	Rotate TLS certs
restart-services	^1.0.0	Apply changes
verify-ssl	^1.0.0	Confirm TLS working

After Creation

Your solution is ready to:

1. Deploy - Execute on target environments
2. Set variables - environment-specific values via variable sets (scoped with scope_environment_id; solution association comes from linking the set to the solution)
3. Promote - Move through your deployment pipeline

Sequence Ordering

Order Considerations

Consider dependencies when ordering:

Common Patterns

Database-First:

1. database-migration
2. deploy-application

Blue-Green:

1. deploy-to-inactive
2. verify-inactive
3. switch-traffic

Canary:

1. deploy-canary
2. monitor-canary
3. deploy-full

Validation

Before saving, Mantis validates:

Check	Description
Sequences exist	All referenced sequences are available
Versions available	Matching versions exist for requirements
Slug uniqueness	No other solution with the same name or equivalent slug (the name is auto-converted to a URL-safe slug)
Valid version format	Semantic version format

Best Practices

1. Keep Solutions Focused

One solution = one deployable unit:

Good	Bad
payment-service	all-services
customer-portal	q4-release
api-gateway	everything

2. Use Meaningful Names

Names should describe what’s being deployed:

Good: customer-portal, order-api, analytics-dashboard
Bad:  app1, solution-v2, new-thing

3. Start with Simple Versions

Begin with 1.0.0 and increment meaningfully:

1.0.0 - Initial release
1.1.0 - Added monitoring sequence
2.0.0 - Major architecture change

4. Document Variables

Add descriptions to help operators understand:

Variable: database_host
Label: Database Hostname
Help: Primary PostgreSQL server hostname

Troubleshooting

Sequence Not in Dropdown

Cause: Sequence has no versions yet

Solution: Add at least one version to the sequence before including it in a solution

Version Requirement Too Restrictive

Cause: No versions match the requirement

Solution: Use a broader requirement (e.g., ^1.0.0 instead of =1.5.3)

Cannot Add Same Sequence Twice

Cause: The API refuses two entries that resolve to the same sequence version — “a sequence may only be listed once”. Lens does not pre-filter the list, so the duplicate is only rejected on submit.

Solution: Two entries for one sequence are allowed when their version requirements resolve differently (say =1.0.0 and =2.0.0). Otherwise keep a single reference.

Next Steps

• Variables - Configure environment-specific values
• Versioning - Manage solution versions
• Promotion Lifecycle - Environment progression
• Overview - Return to solutions overview