@avelor/vhost

Apache virtual host manager. Define your sites in a YAML file, run one command, and Apache is configured.

sudo vhost apply

  ✓  catch-all              protected
  ✓  error pages            /var/www/vhost-errors
  ✓  errors conf            vhost-errors.conf

  ✓  avelor.com            managed   /home/avelor/avelor
  ✓  api.avelor.es          managed   :3000
  ✓  app.avelor.es          managed   :4000

  ✓  apache configtest
  ✓  apache reload

Requirements

• Node.js 18+
• Apache2 with a2ensite, a2enconf, apache2ctl, mod_headers
• Debian / Ubuntu

mod_headers is required for the X-Powered-By response header on error pages. Enable it if not already active:

sudo a2enmod headers && sudo systemctl reload apache2

Install

npm install -g @avelor/vhost

Usage

1. Create sites.yml:

vhost init

2. Add your sites:

sites:
  myblog.com:
    aliases: [www.myblog.com]
    mode: static
    root: /var/www/myblog

  api.myapp.com:
    mode: proxy
    port: 3000

3. Apply:

sudo vhost apply

Apache is configured, enabled, and reloaded.

Commands

| Command | Description | |---|---| | vhost init | Create sites.yml in the current directory | | vhost new [domain] | Add a site interactively (or via flags) | | sudo vhost apply [domain] | Generate configs, enable sites, reload Apache | | sudo vhost remove <domain> | Disable and remove a site | | vhost check | Diff sites.yml against current Apache state | | vhost status | Show enabled sites |

Site configuration

Static site

sites:
  example.com:
    mode: static
    root: /var/www/example.com
    aliases: [www.example.com]   # optional

Reverse proxy

sites:
  api.example.com:
    mode: proxy
    port: 3000
    aliases: [api2.example.com]  # optional

Manual SSL

By default, SSL is left for Certbot to manage. To provide your own certificates:

sites:
  example.com:
    mode: static
    root: /var/www/example.com
    ssl:
      cert: /etc/ssl/certs/example.pem
      key:  /etc/ssl/private/example.key

What apply does

For each site, vhost apply generates a .conf in /etc/apache2/sites-available/ containing:

• HTTP → HTTPS redirect
• HTTPS VirtualHost (static or proxy)
• SSL block (Certbot placeholder or custom cert)
• Per-site error and access logs

It also sets up two pieces of infrastructure the first time:

Catch-all — any request to an unconfigured domain returns a clean error page instead of falling through to the first VirtualHost alphabetically, which is the default Apache behavior.

Error pages — built-in pages for 400, 401, 403, 404, 405, 408, 429, 500, 502, 503, and 504. Each error code has four variants served via content negotiation:

| Accept header | Response | |---|---| | text/html | Styled HTML page | | application/json | { "code": 404, "message": "Page not found.", "source": "@avelor/vhost" } | | application/xml | <error><code>404</code><message>…</message></error> | | text/plain | 404 Page not found. |

All responses include an X-Powered-By: avelor/vhost header. The source field in JSON and the X-Powered-By header make it easy to distinguish vhost error responses from your own API errors.

Useful when the same server hosts both web apps and APIs.

vhost new

Interactive when no flags are given:

$ vhost new

  Domain: api.myapp.com
  Aliases (space-separated, optional):
  Mode: [1] static  [2] proxy → 2
  Proxy port: 3000
  SSL via certbot? [Y/n]:

  ✓  api.myapp.com added to sites.yml

  Next steps:
    sudo vhost apply api.myapp.com
    sudo certbot --apache -d api.myapp.com

Or skip the prompts with flags:

vhost new api.myapp.com --mode proxy --port 3000
vhost new myblog.com --mode static --root /var/www/myblog

Partial flags work too — only the missing fields are asked.

vhost check

Compares sites.yml against Apache's actual state and exits 1 if anything is off.

  ✓  catch-all
  ✓  vhost-errors.conf
  ✓  error pages              /var/www/vhost-errors

  ✓  avelor.com              managed   /home/avelor/avelor
  !  api.avelor.es            manual config   → run: vhost apply api.avelor.es to migrate
  ✖  app.avelor.es            not applied → run: vhost apply app.avelor.es
  !  old.avelor.es            manual config   not in sites.yml

  ✖ 3 issues found.

A site is managed when its .conf was generated by vhost apply. Manual config means the file exists but was written by hand — it works, but sites.yml is not the source of truth yet.

Migrating existing configs

vhost is designed to be adopted gradually. Your existing Apache configs keep working untouched.

The typical flow:

# 1. Set up infrastructure without touching existing sites
sudo vhost apply

# 2. Add one site at a time
vhost new avelor.com --mode static --root /home/avelor/avelor

# 3. Apply only that site — overwrites the manual .conf
sudo vhost apply avelor.com

# 4. Check progress
vhost check

When vhost check shows no manual config warnings, the migration is complete.

License

MIT