Skip to content

shared-services.md

Latest commit

 

History

History
171 lines (120 loc) · 5.2 KB

shared-services.md

File metadata and controls

171 lines (120 loc) · 5.2 KB

Shared Services

Run databases on the host instead of inside each VM - reducing memory usage by 80%, eliminating duplicate data, and speeding up VM creation. One PostgreSQL instance serves all your VMs instead of running N copies.

Supported Services

  • PostgreSQL
  • Redis
  • MongoDB

Benefits

Aspect Per-VM Database (Default) Shared Service
Memory Usage High (e.g., 200MB × N VMs) Low (e.g., 200MB × 1)
Startup Time Added delay to vm start ~5s once (for first VM)
Data Persistence Lost on vm destroy Persistent across VMs
Data Location Scattered inside VMs Centralized in ~/.vm/data
Port Management Potential for conflicts Single, managed port

Enabling Shared Services

Shared services are disabled by default. Enable them globally (all VMs) with --global:

vm config set services.postgresql.enabled true --global
vm config set services.redis.enabled true --global
vm config set services.mongodb.enabled true --global

When you create a VM after enabling a service, the service will be automatically started if it's not already running. It will be automatically stopped when the last VM using it is destroyed.

Connecting to Services

When a shared service is enabled, the VM tool automatically injects environment variables into your VM to make connecting easy.

  • DATABASE_URL for PostgreSQL
  • REDIS_URL for Redis
  • MONGODB_URL for MongoDB

These URLs point to the service running on the host machine.

Example: Connecting to PostgreSQL

Your application can read the DATABASE_URL environment variable to connect:

postgresql://postgres:<auto-generated-password>@${VM_HOST}:5432/my-project

The password is automatically generated and injected into the connection string.

Connection host by provider:

  • Docker: Use host.docker.internal (to reach host from container)
  • Vagrant/Tart: Use localhost or 127.0.0.1

The VM tool automatically configures the correct connection pattern for your provider.

Connection details:

  • Port: 5432 (default, configurable in ~/.vm/config.yaml)
  • User: postgres (default)
  • Password: Auto-generated secure random password (16 characters)
  • Database: Automatically set to your project's name

Security Note: Passwords are automatically generated and stored securely in ~/.vm/secrets/. Each service gets a unique password on first use. To view a service's password:

# View PostgreSQL password
cat ~/.vm/secrets/postgresql.env

# View Redis password
cat ~/.vm/secrets/redis.env

# View MongoDB password
cat ~/.vm/secrets/mongodb.env

The DATABASE_URL and other connection URLs automatically include the correct password, so your applications will connect seamlessly without manual configuration.

Example: Connecting to Redis

Your application can use the REDIS_URL:

redis://${VM_HOST}:6379

Use the same $VM_HOST pattern as PostgreSQL (see above for provider-specific values).

Data Persistence and Location

All data for shared services is stored in your home directory under ~/.vm/data/.

  • PostgreSQL: ~/.vm/data/postgres
  • Redis: ~/.vm/data/redis
  • MongoDB: ~/.vm/data/mongodb

This data persists even when you run vm destroy.

Per-Project Database Isolation

Each project automatically gets its own PostgreSQL database named after the project:

# Project: my-app
DATABASE_URL=postgresql://postgres:<password>@${VM_HOST}:5432/my-app

# Project: other-project
DATABASE_URL=postgresql://postgres:<password>@${VM_HOST}:5432/other-project

Note: The <password> is the same auto-generated password for the PostgreSQL service, shared across all projects.

Redis and MongoDB are shared across all projects (use different key prefixes or collections to separate data).

Configuration

You can customize the port, version, and data directory for each service by editing the global configuration file at ~/.vm/config.yaml.

services:
  postgresql:
    enabled: true
    port: 5432
    version: "16"
    data_dir: ~/.vm/data/postgres
  redis:
    enabled: true
    port: 6379
    version: "7"
    data_dir: ~/.vm/data/redis
  mongodb:
    enabled: true
    port: 27017
    version: "7"
    data_dir: ~/.vm/data/mongodb

Troubleshooting

Check if a service is running

docker ps | grep vm-postgres-global
docker ps | grep vm-redis-global
docker ps | grep vm-mongodb-global

Connect directly to a database

# PostgreSQL (you'll be prompted for the password)
psql -h localhost -p 5432 -U postgres
# Or pass password directly (get it from ~/.vm/secrets/postgresql.env)
PGPASSWORD=$(cat ~/.vm/secrets/postgresql.env) psql -h localhost -p 5432 -U postgres

# Redis (requires password authentication)
redis-cli -h localhost -p 6379
# Then authenticate with: AUTH <password from ~/.vm/secrets/redis.env>

# MongoDB (requires password authentication)
mongosh --host localhost --port 27017 -u root -p $(cat ~/.vm/secrets/mongodb.env)

View service logs

docker logs vm-postgres-global
docker logs vm-redis-global
docker logs vm-mongodb-global