vix deploy runs a production deployment workflow for a Vix application.

Use it when you want to pull the latest code, build the app, run tests, restart the service, verify health, validate proxy configuration, reload Nginx, and optionally rollback on failure.

vix deploy

vix deploy is the production deployment command for Vix.

It can:

• pull the latest code from Git
• build the production app
• run tests before restart
• restart the systemd service
• verify service status
• run health checks
• validate Nginx proxy config
• reload Nginx
• show logs on failure
• run repeated error analysis on failure
• rollback to the previous Git revision when enabled
• run in dry-run mode
• skip pull or tests from the CLI

This command is designed for Linux server deployments where a Vix app is already configured with:

vix service
vix health
vix proxy nginx
vix logs

vix deploy is currently supported on:

Linux

On unsupported platforms, Vix reports:

vix deploy is currently supported on Linux only.

vix deploy [options]

# Run the configured deployment
vix deploy

# Print steps without executing them
vix deploy --dry-run

# Deploy without git pull
vix deploy --no-pull

# Deploy without tests
vix deploy --no-tests

# Show more details
vix deploy --verbose

A configured deployment can run this flow:

print deploy summary
capture current Git revision for rollback
git pull origin <branch>
run build command
run test command
restart service
check service status
run health checks
check Nginx proxy config
reload Nginx
print deployment completed

The exact steps depend on vix.json.

vix deploy reads deployment configuration from:

vix.json

under:

production.deploy

Example:

{
  "name": "PulseGrid",
  "production": {
    "deploy": {
      "pull": true,
      "branch": "main",
      "build": "vix build --preset release",
      "tests": true,
      "test_command": "vix tests",
      "service": "pulsegrid",
      "health_local": true,
      "health_public": true,
      "proxy_check": true,
      "proxy_reload": true,
      "logs_on_failure": true,
      "log_lines": 80,
      "rollback": true
    }
  }
}

If some fields are missing, Vix uses safe defaults.

Common defaults are:

app name: project name
service: app name
branch: main
build command: vix build --preset release
test command: vix tests
log lines: 80

Boolean fields are controlled by your vix.json.

CLI flags can override selected behavior:

vix deploy --no-pull
vix deploy --no-tests

Before executing, Vix prints a deployment summary.

Example output shape:

Deploy
App: PulseGrid
Branch: main
Pull: yes
Build: vix build --preset release
Tests: enabled
Service: pulsegrid
Health local: enabled
Health public: enabled
Proxy check: enabled
Proxy reload: enabled
Logs on failure: enabled
Rollback: enabled
Dry run: no
Verbose: no

This makes the deployment plan visible before the command runs.

Use --dry-run to print the deployment steps without executing them.

vix deploy --dry-run

This is useful before enabling production deployment.

Example output shape:

Deploy
App: PulseGrid
Branch: main
Pull: yes
Build: vix build --preset release
Tests: enabled
Service: pulsegrid
Health local: enabled
Health public: enabled
Proxy check: enabled
Proxy reload: enabled
Logs on failure: enabled
Rollback: enabled
Dry run: yes

Pull
Command: git pull origin 'main'

Build
Command: vix build --preset release

Tests
Command: vix tests

Restart Service
Command: vix service restart

Service Status
Command: vix service status

Health Check
Command: vix health

Proxy Check
Command: vix proxy nginx check

Proxy Reload
Command: vix proxy nginx reload

deployment completed

Dry run helps verify the deployment plan without changing the server.

When enabled, Vix runs:

git pull origin <branch>

Example:

git pull origin 'main'

Config:

{
  "production": {
    "deploy": {
      "pull": true,
      "branch": "main"
    }
  }
}

Skip pull for one deployment:

vix deploy --no-pull

Use --no-pull when the code is already updated manually.

Vix runs the configured build command.

Example:

{
  "production": {
    "deploy": {
      "build": "vix build --preset release"
    }
  }
}

This executes:

vix build --preset release

A stronger build command can include a target:

{
  "production": {
    "deploy": {
      "build": "vix build --preset release --build-target all"
    }
  }
}

Use the build command that matches your production app.

When tests are enabled, Vix runs the configured test command.

Example:

{
  "production": {
    "deploy": {
      "tests": true,
      "test_command": "vix tests"
    }
  }
}

Skip tests for one deployment:

vix deploy --no-tests

Use --no-tests only when you intentionally want to bypass the test step.

After a successful build and optional tests, Vix restarts the service:

vix service restart

Then it checks service status:

vix service status

The service name must be configured.

Example:

{
  "production": {
    "deploy": {
      "service": "pulsegrid"
    }
  }
}

If the service name is missing, Vix reports:

Missing deployment service name.
Fix: add production.deploy.service to vix.json

If either health_local or health_public is enabled, Vix runs:

vix health

Config:

{
  "production": {
    "deploy": {
      "health_local": true,
      "health_public": true
    },
    "health": {
      "service": "pulsegrid.service",
      "local": "http://127.0.0.1:8080/",
      "public": "https://pulsegrid.example.com/"
    }
  }
}

Use health checks to catch broken deployments immediately after restart.

If proxy_check or proxy_reload is enabled, Vix validates the Nginx proxy config:

vix proxy nginx check

Config:

{
  "production": {
    "deploy": {
      "proxy_check": true
    }
  }
}

This is useful when deployment depends on a correct public proxy configuration.

If proxy_reload is enabled, Vix reloads Nginx after a successful proxy check:

vix proxy nginx reload

Config:

{
  "production": {
    "deploy": {
      "proxy_reload": true
    }
  }
}

Reload is only useful when the proxy configuration may change during deployment.

If logs_on_failure is enabled, Vix prints failure logs automatically.

Config:

{
  "production": {
    "deploy": {
      "logs_on_failure": true,
      "log_lines": 80
    }
  }
}

On failure, Vix runs a command shaped like:

vix logs errors --repeated -n 80

This helps you see repeated production errors without manually switching commands.

If rollback is enabled, Vix captures the current Git revision before deployment:

git rev-parse HEAD

If a later step fails, Vix attempts to rollback:

git reset --hard <previous-ref>
run build command again
vix service restart
vix service status

Config:

{
  "production": {
    "deploy": {
      "rollback": true
    }
  }
}

Rollback is useful when a pulled change builds or starts incorrectly.

Rollback depends on Git state.

Rollback may be skipped or fail when:

• the current Git revision could not be captured
• the project is not a Git repository
• local changes prevent clean reset
• the previous revision no longer builds
• service restart fails after rollback

If rollback fails, Vix prints:

rollback failed
Fix: inspect the repository and service manually

Rollback is a safety net, not a replacement for backups or release discipline.

If a step fails, deployment stops.

Typical failure points:

If rollback is enabled, Vix attempts rollback before showing failure logs.

If logs on failure is enabled, Vix runs:

vix logs errors --repeated -n <log_lines>

{
  "name": "PulseGrid",
  "production": {
    "deploy": {
      "pull": true,
      "branch": "main",
      "build": "vix build --preset release",
      "tests": true,
      "test_command": "vix tests",
      "service": "pulsegrid",
      "health_local": true,
      "health_public": true,
      "proxy_check": true,
      "proxy_reload": true,
      "logs_on_failure": true,
      "log_lines": 80,
      "rollback": true
    },
    "health": {
      "service": "pulsegrid.service",
      "local": "http://127.0.0.1:8080/",
      "public": "https://pulsegrid.example.com/"
    },
    "logs": {
      "service": "pulsegrid",
      "nginx_access": "/var/log/nginx/pulsegrid.access.log",
      "nginx_error": "/var/log/nginx/pulsegrid.error.log"
    },
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      },
      "tls": {
        "enabled": true
      }
    }
  }
}

For a simple local server deployment:

{
  "name": "PulseGrid",
  "production": {
    "deploy": {
      "pull": false,
      "build": "vix build --preset release",
      "tests": false,
      "service": "pulsegrid",
      "health_local": true,
      "logs_on_failure": true
    },
    "health": {
      "service": "pulsegrid.service",
      "local": "http://127.0.0.1:8080/"
    }
  }
}

Then run:

vix deploy

For an app behind Nginx and TLS:

{
  "name": "PulseGrid",
  "production": {
    "deploy": {
      "pull": true,
      "branch": "main",
      "build": "vix build --preset release",
      "tests": true,
      "test_command": "vix tests",
      "service": "pulsegrid",
      "health_local": true,
      "health_public": true,
      "proxy_check": true,
      "proxy_reload": true,
      "logs_on_failure": true,
      "log_lines": 120,
      "rollback": true
    },
    "health": {
      "service": "pulsegrid.service",
      "local": "http://127.0.0.1:8080/",
      "public": "https://pulsegrid.example.com/"
    },
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      },
      "tls": {
        "enabled": true
      }
    },
    "logs": {
      "service": "pulsegrid",
      "nginx_access": "/var/log/nginx/pulsegrid.access.log",
      "nginx_error": "/var/log/nginx/pulsegrid.error.log",
      "lines": 120
    }
  }
}

For an app with WebSocket production checks:

{
  "name": "PulseGrid",
  "production": {
    "deploy": {
      "pull": true,
      "branch": "main",
      "build": "vix build --preset release",
      "tests": true,
      "test_command": "vix tests",
      "service": "pulsegrid",
      "health_local": true,
      "health_public": true,
      "proxy_check": true,
      "proxy_reload": true,
      "logs_on_failure": true,
      "rollback": true
    },
    "health": {
      "service": "pulsegrid.service",
      "local": "http://127.0.0.1:8080/",
      "public": "https://pulsegrid.example.com/",
      "websocket": "wss://pulsegrid.example.com/ws"
    },
    "proxy": {
      "domain": "pulsegrid.example.com",
      "http": {
        "port": 8080
      },
      "websocket": {
        "enabled": true,
        "path": "/ws",
        "port": 9090
      },
      "tls": {
        "enabled": true
      }
    }
  }
}

vix deploy runs vix health when health is enabled.

That means configured WebSocket health can be checked as part of the normal health command.

Depending on config, Vix can run:

git pull origin '<branch>'
<build command>
<test command>
vix service restart
vix service status
vix health
vix proxy nginx check
vix proxy nginx reload
vix logs errors --repeated -n <lines>
git reset --hard <previous-ref>

In --dry-run, commands are printed but not executed.

Validate environment before deployment:

vix env check --production

This catches missing production variables before restarting the service.

For database-backed apps, check and backup the database before deployment:

vix db status
vix db backup

A safer deployment flow can be:

vix env check --production
vix db status
vix db backup
vix deploy

vix deploy restarts and verifies the service using:

vix service restart
vix service status

Make sure service installation is already done:

vix service install
vix service start

vix deploy can run:

vix health

when health_local or health_public is enabled.

Configure health endpoints under:

production.health

vix deploy can run:

vix proxy nginx check
vix proxy nginx reload

when proxy validation or reload is enabled.

Configure proxy under:

production.proxy

When logs_on_failure is enabled, Vix runs:

vix logs errors --repeated -n <log_lines>

This helps diagnose failure immediately.

After deployment, inspect full readiness:

vix doctor production

A strong production workflow is:

vix env check --production
vix db status
vix deploy
vix doctor production

vix env check --production
vix build --preset release
vix service install
vix service start
vix proxy nginx init
vix health
vix doctor production

Then configure production.deploy.

After that:

vix deploy

vix env check --production
vix db status
vix db backup
vix deploy
vix doctor production

vix deploy --dry-run

vix deploy --no-pull

vix deploy --no-tests

vix logs errors --repeated
vix service status
vix health
vix proxy nginx check

Wrong:

vix deploy

before service setup.

Correct:

vix service install
vix service start
vix deploy

Wrong:

{
  "production": {
    "deploy": {
      "build": "vix build --preset release"
    }
  }
}

Correct:

{
  "production": {
    "deploy": {
      "service": "pulsegrid",
      "build": "vix build --preset release"
    }
  }
}

Wrong:

{
  "production": {
    "deploy": {
      "health_local": true
    }
  }
}

without:

{
  "production": {
    "health": {
      "local": "http://127.0.0.1:8080/"
    }
  }
}

Correct: configure production.health.

Wrong:

{
  "production": {
    "deploy": {
      "proxy_check": true
    }
  }
}

without production.proxy.

Correct: configure proxy first:

vix proxy nginx init
vix proxy nginx check

Rollback needs Git.

If the current Git revision cannot be captured, rollback may be skipped.

Check:

git rev-parse HEAD

For SQLite apps, do not deploy risky changes without:

vix db backup

vix deploy rollback resets Git and restarts the service.

It does not rollback database migrations or restore database backups.

Back up the database separately before deployment.

Run:

git status
git pull origin main

Common causes:

• local uncommitted changes
• wrong branch
• remote authentication failure
• merge conflict
• network failure

Run the configured build command manually.

Example:

vix build --preset release

Then inspect errors.

Run the configured test command manually.

Example:

vix tests

Run:

vix service restart
vix service status
vix service logs

Run:

vix service status
vix logs app --errors

Run:

vix health
vix logs errors --repeated

If local health fails, inspect app/service.

If public health fails, inspect proxy and TLS.

Run:

vix proxy nginx check

Then fix production.proxy or regenerate proxy config.

Run:

sudo nginx -t
vix proxy nginx reload

Inspect manually:

git status
vix build --preset release
vix service status
vix logs errors --repeated

Run vix deploy --dry-run before trusting a new deployment config.

Keep deployment config in vix.json.

Use --no-pull only when code is already updated.

Use --no-tests only when intentionally bypassing tests.

Enable logs_on_failure.

Enable rollback for Git-based deployments.

Back up SQLite databases before deployment.

Run vix env check --production before deployment.

Run vix doctor production after deployment.

Keep health checks lightweight and reliable.

Use explicit build and test commands.

Do not treat Git rollback as database rollback.

Check production readiness.

Open the production doctor guide