Deployment

Learn about the deployment workflow, workspace concepts, and environment management in Tailor Platform

The Tailor Platform SDK provides a streamlined deployment workflow using the apply and remove commands. This guide covers how deployment works, workspace management, and best practices for production deployments.

Deployment Workflow

The basic deployment workflow consists of two main commands:

# Deploy application to workspace
tailor-sdk apply

# Remove application from workspace
tailor-sdk remove

The Apply Command

The apply command deploys your application to a Tailor Platform workspace:

tailor-sdk apply --workspace-id <WORKSPACE_ID>

1. Configuration Loading

   The SDK reads tailor.config.ts and loads all service definitions from the specified file patterns.

2. Type Generation

   Automatically generates TypeScript types if plugins are configured.

3. Bundling

   Bundles all code (resolvers, executors, workflows) for deployment.

4. Schema Validation

   Validates TailorDB schema changes against migration snapshots (unless --no-schema-check is specified).

5. Migration Execution

   Automatically applies pending database migrations if configured.

6. Resource Deployment

   Deploys all resources (databases, resolvers, executors, workflows, auth, etc.) to the workspace.

Apply Options

tailor-sdk apply [options]

--workspace-id · string

Target workspace ID for deployment. Can also be set via TAILOR_PLATFORM_WORKSPACE_ID environment variable.

--profile · string

Workspace profile name. Profiles combine user credentials and workspace IDs.

--config · string · default: "tailor.config.ts"

Path to SDK configuration file.

--yes · boolean · default: "false"

Skip confirmation prompts. Useful for CI/CD pipelines.

--dry-run · boolean · default: "false"

Run the command without making any changes. Shows what would be deployed.

--no-schema-check · boolean · default: "false"

Skip schema diff check against migration snapshots. Not recommended for production.

--no-cache · boolean · default: "false"

Disable bundle caching for this run.

--clean-cache · boolean · default: "false"

Clean the bundle cache before building.

The Remove Command

The remove command removes all resources managed by your application from the workspace:

tailor-sdk remove --workspace-id <WORKSPACE_ID>

This will delete all data in TailorDB tables and remove all deployed resources. This action cannot be undone.

Workspaces

Workspaces are isolated environments for your applications. Each workspace has its own:

• Database instances
• Deployed services (resolvers, executors, workflows)
• Auth and IdP configurations
• Static websites
• Secrets and environment variables

Creating Workspaces

Create a new workspace:

tailor-sdk workspace create \
  --name my-workspace \
  --region us-west

--name · string · required

Workspace name.

--region · string · required

Workspace region. Options: us-west, asia-northeast.

--delete-protection · boolean · default: "false"

Enable delete protection to prevent accidental deletion.

--profile-name · string

Automatically create a profile for this workspace.

Listing Workspaces

tailor-sdk workspace list

Deleting Workspaces

tailor-sdk workspace delete --workspace-id <WORKSPACE_ID>

Profiles

Profiles combine user credentials and workspace IDs for easier deployment management:

Creating Profiles

tailor-sdk profile create production \
  --user [e-mail] \
  --workspace-id <WORKSPACE_ID>

Using Profiles

Deploy using a profile:

tailor-sdk apply --profile production

Or set via environment variable:

export TAILOR_PLATFORM_PROFILE=production
tailor-sdk apply

Listing Profiles

tailor-sdk profile list

Environment Management

Environment Variables in Config

Define environment variables in tailor.config.ts:

tailor.config.ts

export default defineConfig({
  name: "my-app",
  env: {
    API_KEY: "your-api-key",
    DATABASE_URL: "https://api.example.com",
    FEATURE_FLAG: true,
  },
});

Loading from .env Files

Load environment variables from files during deployment:

# Load from .env (required)
tailor-sdk apply --env-file .env

# Load from .env and .env.local (optional if exists)
tailor-sdk apply --env-file .env --env-file-if-exists .env.local

# Load multiple files
tailor-sdk apply --env-file .env --env-file .env.production

Environment files follow Node.js --env-file behavior:

• Variables already set in the environment are not overwritten
• Later files override earlier files
• --env-file files are loaded first, then --env-file-if-exists files

Environment Variable Priority

Environment variables are resolved in this order:

1. Variables already set in the shell environment
2. Variables from --env-file (in order specified)
3. Variables from --env-file-if-exists (in order specified)
4. Variables defined in tailor.config.ts

Migration Handling

When database migrations are configured, apply automatically handles migration execution:

tailor.config.ts

export default defineConfig({
  db: {
    tailordb: {
      files: ["./tailordb/*.ts"],
      migration: {
        directory: "./migrations",
      },
    },
  },
});

Migration Execution Flow

1. Detect Pending Migrations

   The SDK detects migration scripts that haven’t been executed yet.

2. Apply Pre-Migration Schema

   Applies schema changes needed before running migration scripts.

3. Execute Migration Scripts

   Runs migration scripts in order via TestExecScript API.

4. Apply Post-Migration Schema

   Applies remaining schema changes after migration scripts.

5. Update Migration State

   Updates migration state labels in TailorDB metadata.

Schema Verification

By default, apply performs two verification steps:

Local Schema Check

Verifies that local schema changes match the migration files. This ensures migrations are properly generated before deployment.

Remote Schema Check

Verifies that the remote schema matches the expected state based on migration history. This detects schema drift caused by manual changes or other developers.

If remote schema drift is detected, the apply will fail with an error showing the differences. This prevents applying migrations to an inconsistent state.

Authentication

Login to Tailor Platform

tailor-sdk login

This opens a browser window for authentication and stores credentials locally.

Authentication Priority

Authentication tokens are resolved in this order:

1. TAILOR_PLATFORM_TOKEN environment variable
2. TAILOR_TOKEN environment variable (deprecated)
3. Profile specified via --profile option or TAILOR_PLATFORM_PROFILE
4. Current user from platform config (~/.config/tailor-platform/config.yaml)

Using Personal Access Tokens

For CI/CD pipelines, use personal access tokens:

# Create a token
tailor-sdk user pat create --name ci-token

# Use in CI/CD
export TAILOR_PLATFORM_TOKEN=<token>
tailor-sdk apply --yes

CI/CD Best Practices

1. Use Personal Access Tokens

   Create a dedicated token for CI/CD and store it as a secret:

   export TAILOR_PLATFORM_TOKEN=${{ secrets.TAILOR_TOKEN }}
   
2. Use Profiles or Workspace IDs

   Explicitly specify the target workspace:

   tailor-sdk apply --workspace-id <WORKSPACE_ID> --yes
   
3. Load Environment Files

   Use environment files for different stages:

   tailor-sdk apply \
     --env-file .env \
     --env-file .env.production \
     --yes
   
4. Enable Auto-Confirm

   Skip interactive prompts in CI/CD:

   tailor-sdk apply --yes
   

Example GitHub Actions Workflow

.github/workflows/deploy.yml

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: actions/setup-node@v3
        with:
          node-version: 20
      
      - name: Install dependencies
        run: npm install
      
      - name: Deploy to Tailor Platform
        env:
          TAILOR_PLATFORM_TOKEN: ${{ secrets.TAILOR_TOKEN }}
          TAILOR_PLATFORM_WORKSPACE_ID: ${{ secrets.WORKSPACE_ID }}
        run: |
          npx tailor-sdk apply \
            --env-file .env.production \
            --yes

Deployment Checklist

• Migrations are generated and committed
• Environment variables are configured
• Target workspace is correct
• Authentication is set up (profile or token)
• Tests pass locally
• Schema changes are reviewed
• Dry-run deployment succeeds

Next Steps

Configuration

Learn about tailor.config.ts structure

Type Safety

Understand TypeScript type flow