Vxero Neo

What is Vxero Neo?

Vxero Neo (Neo) is an SSH-native command-line tool for deploying Docker applications to a VPS. It connects to your server over SSH, sets up Docker and Caddy, and deploys your apps with HTTPS via auto-SSL—without installing an agent or using a separate control plane.

Neo also manages application lifecycle steps from local development through staging and production. It reads your local project configuration (including docker-compose.yml, .env, and .neo.yml), builds and transfers images over SSH, performs health checks, and swaps traffic with zero downtime.

Key Features

• SSH-only deployment flow (no agent, no dashboard): Neo runs on your local machine and connects to your VPS via SSH; beyond Docker/Caddy for your runtime, it doesn’t require additional server-side tooling.
• Automated server initialization (Docker + Caddy): During deployment, Neo sets up Docker and Caddy on the target server so your containers can run and receive HTTPS traffic.
• From compose/config to a live switch: Neo reads your local config, builds the image, transfers it over SSH, then swaps traffic after health checks; old containers keep running until the switch.
• Instant HTTPS domain and alternative certificate options: Neo can provision HTTPS using sslip.io (no DNS needed) with --temp. For real domains, it can use Let’s Encrypt via Caddy (after DNS is pointed), or accept your own cert with --cert and --key.
• Config generation and environment management: neo config generate scans docker-compose.yml and auto-generates .neo.yml by detecting the app service, sidecars, workers, environment variables, and volumes. Neo can also sync env/state via commands like neo env and neo sync.
• Blue-green style zero-downtime deploys: It starts the new containers, waits for health checks, and then performs the traffic swap so the previous version remains available until the cutover.
• Workers, sidecars, and persistent volumes: Define background workers and sidecars in .neo.yml so they deploy alongside the main app with shared volumes and environment vars. Declare volumes in .neo.yml to persist data across redeploys.
• Multi-server and per-environment settings: Use flags such as --to staging to deploy to staging or production; each environment can have its own domain, environment variables, and SSL configuration.

How to Use Vxero Neo

1. Prepare your project: Ensure your app is described with docker-compose.yml (and optional .env).
2. Generate Neo’s deployment config: In your project directory, run neo config generate. Neo scans docker-compose.yml and writes .neo.yml with detected services such as the app, workers/sidecars (if defined/detected), environment variables, and volumes.
3. Develop locally (optional but supported): Use neo dev to wrap docker-compose with Neo’s environment loading from .neo.yml.
4. Deploy over SSH: Run neo deploy targeting your VPS. Neo builds the image from your Dockerfile (and compose-derived configuration), transfers it over SSH, then performs health checks and swaps traffic.
5. Enable HTTPS: Use neo domain --temp for an sslip.io-based instant HTTPS URL, or use a real domain with Let's Encrypt auto-SSL once DNS is pointed, or provide --cert/--key for your own certificate.

Use Cases

• Single-VM Docker app deployments: Deploy one containerized application per VPS (e.g., a web service) where you want SSH-based automation rather than a cluster orchestrator.
• Staging → production with shared config: Use the same config across environments (via .neo.yml generation and env loading), deploying to staging and then promoting to production with different domains/SSL settings.
• Apps with sidecars and background workers: Deploy a main app alongside worker and sidecar containers defined in .neo.yml, including shared environment variables and volumes.
• Projects that need quick HTTPS without DNS changes: Use neo domain --temp to get an immediate HTTPS URL for testing with sslip.io, then later switch to a real domain when DNS is ready.
• Zero-downtime releases for small teams: Perform blue-green style updates with health checks so the old version stays up until the new containers are ready.

FAQ

• Does Neo install an agent on my server? No. Neo runs on your local machine and connects to your VPS via SSH. The only things set up on the server are Docker and Caddy for your application runtime.

• I already use docker-compose. How do I switch to Neo? Run neo config generate in your project directory. Neo scans docker-compose.yml and auto-generates .neo.yml, then you can use neo deploy to ship the app.

• What cloud providers are supported? Neo can deploy to any VPS that provides SSH access, such as DigitalOcean, Hetzner, Linode, Vultr, AWS EC2, GCP, and Azure. Neo deploys to a single VM (it is not a multi-node cluster orchestrator like Kubernetes or Docker Swarm).

• How does HTTPS work? Neo supports neo domain --temp for instant HTTPS via sslip.io, neo domain app example.com for Let’s Encrypt auto-SSL after DNS is pointed, and --cert/--key to use your own certificate.

• Can Neo run background workers and databases? Workers can be declared in .neo.yml and are deployed as separate containers using the same image, env vars, and volumes. For databases, Neo can run them as Docker sidecars/services for smaller projects; for production with real users, it recommends managed databases.

Alternatives

• Manual Docker + Caddy deployment scripts: If you prefer full control and already have your own deployment automation, you can build and transfer images, run containers, and manage Caddy/SSL yourself. This typically requires more setup effort than Neo’s single-command workflow.
• Docker Swarm or Kubernetes: These are cluster orchestrators for multi-node deployments. They differ from Neo by targeting orchestration across clusters rather than a single SSH-accessible VPS.
• Other VPS-centric CI/CD pipelines: You can use generic CI/CD tools to SSH into a server, build images, and restart containers. Compared to Neo, you’d handle config generation, zero-downtime switching logic, and HTTPS integration yourself.
• Managed container platforms: Platforms that manage routing and TLS can reduce infrastructure steps. They usually trade away the SSH-first, “no agent/control plane” deployment model described for Neo.