Skip to content

Advanced Configuration Guide

Master The Stratus configuration with this comprehensive guide. Learn how to optimize your sync settings, manage multiple profiles, and fine-tune performance.

Configuration Location: All settings are stored in .stratus/config.json in your workspace root.

Configuration File Structure

The Stratus uses a JSON-based configuration file with the following structure:

{
  "version": "1.0",
  "activeProfile": "production",
  "globalSettings": {
    "autoSync": true,
    "logLevel": "info",
    "parallelUploads": 3
  },
  "profiles": {
    "production": { /* Profile configuration */ }
  }
}

Global Settings

These settings apply to all profiles unless overridden:

autoSync

  • Type: Boolean
  • Default: true
  • Description: Enable or disable automatic sync on file save
"autoSync": true

logLevel

  • Type: String
  • Options: "debug", "info", "warn", "error"
  • Default: "info"
  • Description: Set logging verbosity
"logLevel": "debug"

parallelUploads

  • Type: Number
  • Range: 1-10 (Pro users), 1-3 (Free users)
  • Default: 3
  • Description: Number of concurrent file uploads
"parallelUploads": 5

Profile Configuration

Each profile represents a deployment target (development, staging, production, etc.):

name

  • Type: String
  • Required: Yes
  • Description: Human-readable profile name
"name": "production"

provider

  • Type: String
  • Required: Yes
  • Options: "aws-s3", "gcs", "azure-blob", "ftp", "sftp", "do-spaces"
  • Description: Cloud storage provider type
"provider": "aws-s3"

uploadOnSave

  • Type: Boolean
  • Default: true
  • Description: Auto-upload files when saved
"uploadOnSave": true

watchPatterns

  • Type: Array of strings (glob patterns)
  • Default: ["**/*"]
  • Description: Files to watch for changes
"watchPatterns": [
  "dist/**/*",
  "build/**/*.{js,css,html}"
]

ignorePatterns

  • Type: Array of strings (glob patterns)
  • Default: See below
  • Description: Files to exclude from sync
"ignorePatterns": [
  "**/node_modules/**",
  "**/.git/**",
  "**/.vscode/**",
  "**/.stratus/**",
  "**/*.log",
  "**/.DS_Store"
]

compareBy

  • Type: String
  • Options: "md5", "size", "timestamp"
  • Default: "timestamp" (Free), "md5" (Pro)
  • Description: How to determine if a file has changed
"compareBy": "md5"

retryAttempts

  • Type: Number
  • Range: 0-10
  • Default: 3
  • Description: Number of retry attempts for failed uploads
"retryAttempts": 5

retryDelay

  • Type: Number (milliseconds)
  • Default: 1000
  • Description: Delay between retry attempts
"retryDelay": 2000

VS Code Settings

You can also configure The Stratus through VS Code settings (settings.json):

{
  "thestratus.enabled": true,
  "thestratus.configPath": ".stratus/config.json",
  "thestratus.autoSync": true,
  "thestratus.showStatusBar": true,
  "thestratus.logLevel": "info",
  "thestratus.parallelUploads": 3,
  "thestratus.licenseKey": ""
}

Provider-Specific Settings

AWS S3

"config": {
  "accessKeyId": "AKIA...",
  "secretAccessKey": "********",
  "region": "us-east-1",
  "bucket": "my-bucket",
  "prefix": "optional/path/",
  "acl": "public-read",
  "cacheControl": "max-age=3600",
  "storageClass": "STANDARD",
  "serverSideEncryption": "AES256"
}

Google Cloud Storage (Pro)

"config": {
  "projectId": "my-project",
  "keyFilename": "/path/to/key.json",
  "bucket": "my-bucket",
  "prefix": "optional/path/",
  "storageClass": "STANDARD",
  "predefinedAcl": "publicRead"
}

Azure Blob Storage (Pro)

"config": {
  "connectionString": "DefaultEndpointsProtocol=https;...",
  "containerName": "my-container",
  "prefix": "optional/path/",
  "accessTier": "Hot",
  "blobHTTPHeaders": {
    "blobCacheControl": "max-age=3600"
  }
}

FTP / SFTP

"config": {
  "host": "ftp.example.com",
  "port": 22,
  "username": "user",
  "password": "********",
  "privateKey": "/path/to/key",
  "passphrase": "optional",
  "prefix": "www/",
  "secure": true
}

Complete Example

Here's a complete configuration with multiple profiles:

{
  "version": "1.0",
  "activeProfile": "production",
  "globalSettings": {
    "autoSync": true,
    "logLevel": "info",
    "parallelUploads": 5
  },
  "profiles": {
    "development": {
      "name": "development",
      "provider": "sftp",
      "config": {
        "host": "dev.example.com",
        "port": 22,
        "username": "devuser",
        "privateKey": "~/.ssh/id_rsa",
        "prefix": "www/"
      },
      "uploadOnSave": true,
      "compareBy": "timestamp",
      "ignorePatterns": [
        "**/node_modules/**",
        "**/.git/**"
      ]
    },
    "staging": {
      "name": "staging",
      "provider": "aws-s3",
      "config": {
        "region": "us-east-1",
        "bucket": "staging-myapp",
        "acl": "private"
      },
      "uploadOnSave": true,
      "compareBy": "md5",
      "watchPatterns": ["dist/**/*"]
    },
    "production": {
      "name": "production",
      "provider": "aws-s3",
      "config": {
        "region": "us-east-1",
        "bucket": "myapp.com",
        "acl": "public-read",
        "cacheControl": "max-age=31536000, immutable"
      },
      "uploadOnSave": false,
      "compareBy": "md5",
      "watchPatterns": ["dist/**/*"],
      "retryAttempts": 5
    }
  }
}

Environment Variables

You can use environment variables for sensitive data:

{
  "config": {
    "accessKeyId": "${AWS_ACCESS_KEY_ID}",
    "secretAccessKey": "${AWS_SECRET_ACCESS_KEY}"
  }
}

Best Practices

Security

  • Add .stratus/config.json to .gitignore
  • Use environment variables for credentials
  • Use IAM roles with least privilege
  • Rotate access keys regularly

Performance

  • Use watchPatterns to sync only built files
  • Increase parallelUploads for faster deployments (Pro)
  • Use MD5 comparison to avoid re-uploading unchanged files
  • Set appropriate cache headers for static assets

Workflow

  • Enable uploadOnSave for dev/staging
  • Disable uploadOnSave for production (manual deploys)
  • Use different profiles for different environments
  • Keep comprehensive ignorePatterns

Next Steps