Local Storage

Store deployment scripts on the local filesystem.

Overview

Local storage provides direct access to scripts stored on the Mantis server’s filesystem:

When to Use Local Storage

Use Case	Recommendation
Development	Ideal for quick iteration
Single server	Works well without external dependencies
Air-gapped	Only option without network storage
Testing	Fast access for test scripts
Migration	Temporary storage during system migration

Configuration

Properties

Property	Required	Description
Name	Yes	Unique identifier for the storage
File System Path	Yes	Absolute path to scripts directory (field labelled “File System Path”)

Creating Local Storage

Via Lens UI

┌─────────────────────────────────────────────────────────────┐
│  Create Local Storage                                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Name *                                                     │
│  [scripts                                  ]                │
│                                                             │
│  File System Path *                                         │
│  [/var/mantis/scripts                      ]                │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ Path must be an absolute path accessible by the       │  │
│  │ Mantis server process.                                │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│                                     [Cancel]  [Create]      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1. Navigate to Storage in the sidebar (under Infrastructure)
2. Click New Storage
3. Click the Local Storage tab
4. Enter a unique name
5. Enter the absolute path
6. Click Create Local Storage

Via REST API

Global-admin tokens must include tenant_id. Storage creation calls resolve_tenant_id_for_write, which rejects with 400 tenant_id is required for storage creation when it resolves to None — exactly the case for an admin token that omits it. Add "tenant_id": "<uuid>" to the request body (or use a tenant-scoped token, which supplies it automatically).

# 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 with a different base path
curl -X POST "$MANTIS_URL/api/v1/storage/local" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "dev-scripts", "path": "/home/deploy/scripts"}'

Directory Structure

Recommended Layout

Organize scripts within the storage directory:

/var/mantis/scripts/
├── deploy/
│   ├── web-app.sh
│   ├── api-service.sh
│   └── database.sh
├── configure/
│   ├── nginx.sh
│   ├── ssl-certs.sh
│   └── firewall.sh
├── health/
│   ├── check-web.sh
│   └── check-database.sh
└── rollback/
    └── restore-backup.sh

Referencing Scripts

When creating actions, reference scripts relative to the storage path:

Storage Path	Filename	Full Path
/var/mantis/scripts	deploy/web-app.sh	/var/mantis/scripts/deploy/web-app.sh
/var/mantis/scripts	configure/nginx.sh	/var/mantis/scripts/configure/nginx.sh

Detail View

┌─────────────────────────────────────────────────────────────┐
│  Local Storage: scripts                                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Type: Local                                                │
│  Path: /var/mantis/scripts                                  │
│  Created: January 15, 2024                                  │
│                                                             │
│  (The detail page shows Name / ID / Path / Created / Last   │
│   Updated only — there is no "Used By" consumers list.)     │   │
│                                                             │
│                                        [Edit] [Delete]      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Permissions

Server Process

The Mantis server process must have read access to the storage directory:

# Check current permissions
ls -la /var/mantis/scripts/

# Set appropriate ownership
chown -R mantis:mantis /var/mantis/scripts/

# Set appropriate permissions
chmod -R 755 /var/mantis/scripts/

Permission Requirements

Action	Permission Needed
Read scripts	r (read)
List directory	r and x (read + execute on directory)

SELinux/AppArmor

If using SELinux or AppArmor, ensure the Mantis process has access:

# SELinux example
semanage fcontext -a -t mantis_script_t "/var/mantis/scripts(/.*)?"
restorecon -Rv /var/mantis/scripts/

Managing Scripts

Adding Scripts

Scripts can be added directly to the filesystem:

# Copy script to storage
cp deploy.sh /var/mantis/scripts/deploy/

# Set executable permission
chmod +x /var/mantis/scripts/deploy/deploy.sh

Updating Scripts

Update scripts in place:

# Edit script
vim /var/mantis/scripts/deploy/web-app.sh

# Or copy updated version
cp ~/new-deploy.sh /var/mantis/scripts/deploy/web-app.sh

Caution

Changes to local scripts take effect immediately. Consider using Git storage for version control in production.

Removing Scripts

# Remove script
rm /var/mantis/scripts/deploy/old-script.sh

Caution

Ensure no actions reference the script before removing.

Multi-Server Deployments

Challenge

Local storage doesn’t automatically sync across multiple Mantis servers:

┌─────────────────┐         ┌─────────────────┐
│  Mantis Server 1│         │  Mantis Server 2│
│  ┌───────────┐  │         │  ┌───────────┐  │
│  │ /scripts/ │  │    ?    │  │ /scripts/ │  │
│  │ deploy.sh │  │  ─────  │  │   (empty) │  │
│  └───────────┘  │         │  └───────────┘  │
└─────────────────┘         └─────────────────┘

Solutions

Solution	Description
Shared filesystem	NFS, EFS, or similar network filesystem
Configuration management	Ansible, Puppet, Chef to sync scripts
Git storage	Use Git storage instead for automatic sync
S3 storage	Use S3 storage for centralized access

Shared Filesystem Example

# Mount NFS share for scripts
mount -t nfs storage-server:/exports/scripts /var/mantis/scripts

# Add to fstab for persistence
echo "storage-server:/exports/scripts /var/mantis/scripts nfs defaults 0 0" >> /etc/fstab

Best Practices

1. Use Absolute Paths

Always configure with absolute paths:

Good	Avoid
/var/mantis/scripts	./scripts
/home/deploy/scripts	~/scripts
/opt/mantis/scripts	scripts/

2. Consistent Directory Structure

Organize scripts logically:

/var/mantis/scripts/
├── by-solution/         # Organized by solution
│   ├── customer-portal/
│   └── auth-service/
├── by-action/           # Organized by action type
│   ├── deploy/
│   ├── configure/
│   └── rollback/
└── shared/              # Common scripts
    └── utilities.sh

3. Version Control Externally

If using local storage, maintain version control separately:

# Keep scripts in Git repository
cd /var/mantis/scripts
git init
git add .
git commit -m "Initial scripts"

4. Backup Regularly

Include local storage in backup strategy:

# Backup scripts
tar -czvf scripts-backup-$(date +%Y%m%d).tar.gz /var/mantis/scripts/

Troubleshooting

“File not found” Error

Cause: Script doesn’t exist at specified path

Solution:

1. Verify file exists: ls -la /var/mantis/scripts/deploy.sh
2. Check filename is correct (case-sensitive)
3. Ensure path includes subdirectories if used

“Permission denied” Error

Cause: Mantis process lacks read permission

Solution:

1. Check file permissions: ls -la /var/mantis/scripts/
2. Fix ownership: chown mantis:mantis /var/mantis/scripts/*
3. Fix permissions: chmod 755 /var/mantis/scripts/*

Storage Not Accessible After Restart

Cause: Path changed or mount point not restored

Solution:

1. Verify mount is active: mount | grep scripts
2. Check fstab for persistent mounts
3. Remount if needed: mount -a

Next Steps

• Git Storage - Version-controlled scripts
• S3 Storage - Cloud artifact storage
• Overview - Return to storage overview