Storage Backends

Manage where deployment scripts and artifacts are stored.

What is a Storage Backend?

Storage backends define where Mantis retrieves scripts and artifacts for deployments:

Storage Types

Mantis supports three storage backend types:

Type	Best For	Features
Local	Development, single-server	Simple paths, fast access
Git	Version control, GitOps	Branch tracking, audit trail
S3	Large artifacts, distributed	Multi-region, immutable storage

Choosing a Storage Type

Local Storage

Best when:

• Development and testing
• Single-server deployments
• Air-gapped environments without network storage
• Quick setup without external dependencies

Git Storage

Best when:

• Scripts need version control
• GitOps workflows with PR-based changes
• Audit trails via Git history are required
• Multiple teams collaborate on deployment scripts

S3 Storage

Best when:

• Large deployment artifacts
• Multi-region deployments
• Immutable artifact storage
• Cloud-native infrastructure

Storage List View

┌─────────────────────────────────────────────────────────────┐
│  Storage Backends                                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Search: [____________________________] [+ New Storage]     │
│                                                             │
│  ┌────────────────┬────────┬─────────────────┬───────────┐ │
│  │ Name           │ Type   │ Location        │ Actions   │ │
│  ├────────────────┼────────┼─────────────────┼───────────┤ │
│  │ scripts        │ Local  │ /var/mantis/... │ [View]    │ │
│  │ deploy-repo    │ Git    │ github.com/...  │ [View]    │ │
│  │ artifacts      │ S3     │ s3://bucket/... │ [View]    │ │
│  └────────────────┴────────┴─────────────────┴───────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

How Scripts Use Storage

Actions reference scripts from storage backends:

Script Reference Example

When creating an action, you specify the storage and filename:

┌─────────────────────────────────────────────────────────────┐
│  Create Action                                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Name:     [deploy-app                    ]                 │
│                                                             │
│  Payload Type: ● Script  ○ Command                          │
│                                                             │
│  Storage:  [scripts               ▼]                        │
│  Filename: [deploy.sh                     ]                 │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ Script will be read from:                             │  │
│  │ /var/mantis/scripts/deploy.sh                         │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Security

Path Traversal Protection

All storage backends implement path traversal protection:

Protection	Description
Null bytes	Rejected
Absolute paths	Rejected
Parent traversal	../ sequences rejected
Canonicalization	Paths verified within storage root
Symlink protection	Files read with O_NOFOLLOW (Unix)

Example: Blocked Access

# These filenames are blocked:
../../../etc/passwd    # Parent traversal
/etc/passwd           # Absolute path
script�.sh         # Null byte injection

Credential Security

Sensitive credentials are encrypted at rest:

Storage Type	Encrypted Fields
Git	SSH private key, SSH passphrase, password
S3	Access key ID, secret access key

Encryption uses AES-256-GCM with AAD binding.

Creating a Storage Backend

Via Lens UI

1. Navigate to Storage in the sidebar (under Infrastructure)
2. Click New Storage
3. Click the tab for your storage type
4. Configure backend-specific settings
5. Click Create

Via REST API

Storage sources are managed in Lens or through the /api/v1/storage/* endpoints (there is no mantisctl storage subcommand). Each backend has its own endpoint:

# Create local storage
curl -X POST "$MANTIS_URL/api/v1/storage/local" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "scripts", "path": "/var/mantis/scripts"}'

# Create git storage (auth_id references a git auth credential)
curl -X POST "$MANTIS_URL/api/v1/storage/git" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "deploy-repo",
    "path": "/var/mantis/git/deploy-repo",
    "url": "https://github.com/org/scripts.git",
    "reference": "main",
    "auth_id": "<git-auth-id>"
  }'

# Create S3 storage (static credentials)
curl -X POST "$MANTIS_URL/api/v1/storage/s3" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "artifacts",
    "bucket": "my-artifacts-bucket",
    "region": "us-west-2",
    "path_prefix": "deployments/",
    "auth_type": "static",
    "access_key_id": "AKIA...",
    "secret_access_key": "..."
  }'

Storage Configuration

Common Settings

Setting	Required	Description
Name	Yes	Unique identifier
Type	Yes	Local, Git, or S3

Type-Specific Settings

See detailed configuration guides:

• Local Storage
• Git Storage
• S3 Storage

Best Practices

1. Use Git for Version Control

Store deployment scripts in Git for:

• Change history and audit trails
• PR-based review workflows
• Rollback to previous versions

2. Use S3 for Large Artifacts

Use S3 for binary artifacts:

• Application packages
• Container images
• Large data files

3. Use Local for Development

Local storage is ideal for:

• Quick iteration during development
• Testing new scripts
• Air-gapped environments

4. Organize by Purpose

Create separate storages for different purposes:

Storage Backends:
├── scripts-local     # Development scripts
├── scripts-git       # Production scripts (version controlled)
├── artifacts-dev     # Development artifacts
└── artifacts-prod    # Production artifacts

Troubleshooting

Cannot Read Script from Storage

Cause: File doesn’t exist or path is incorrect

Solution:

1. Verify file exists in storage location
2. Check filename spelling (case-sensitive)
3. Ensure storage backend is accessible

Git Storage Not Updating

Cause: Cache or authentication issues

Solution:

1. Check last fetch time
2. Verify authentication credentials
3. Manually trigger refresh

S3 Access Denied

Cause: Insufficient permissions

Solution:

1. Check IAM policy allows required actions
2. Verify bucket policy
3. Confirm credential configuration

Next Steps

• Local Storage - Configure local file storage
• Git Storage - Set up Git repositories
• S3 Storage - Configure S3 buckets
• Authentication - Manage storage credentials