Automated Install

The automated installation script is the fastest and easiest way to set up Actvt remote server monitoring. This single command handles all the complexity of installation, configuration, and setup.

Quick Start

On your remote server, set the required environment variables and run the installer:

export ACTVT_DOMAIN="monitor.yourdomain.com"
export ACTVT_EMAIL="[email protected]"
curl -L https://actvt.io/install | bash

Notes:

• ACTVT_DOMAIN is required. ACTVT_EMAIL is required for non-interactive mode; in interactive mode you will be prompted and can optionally skip it.
• The script auto-detects if nginx is present and will run in proxy mode behind nginx; otherwise it runs in standalone mode.
• See Installation Modes for detailed explanation of auto/standalone/proxy modes.

What the Script Does

The automated installation script performs the following tasks:

1. System Detection & Validation

• Detects your Linux distribution (Ubuntu, Debian, CentOS, RHEL, Amazon Linux)
• Checks for root/sudo access
• Verifies system requirements (CPU, RAM, storage)
• Tests internet connectivity

2. Vector Installation

• Adds Vector's official package repository
• Installs Vector using your distribution's package manager
• Sets up systemd service for automatic startup
• Creates necessary directories and users

3. Configuration

• Generates optimized Vector configuration
• Automatically detects NVIDIA GPUs for optional monitoring
• Configures WebSocket server on port 4096
• Sets up proper permissions and security

4. TLS Certificate Setup

• Prompts for your domain name
• Installs Certbot (Let's Encrypt client)
• Obtains free SSL/TLS certificates
• Installs certificates for Vector by copying them into /etc/vector/certs with secure ownership/permissions
• Configures automatic certificate renewal via a Certbot deploy hook that refreshes /etc/vector/certs and reloads Vector

5. Firewall Configuration

• Detects firewall type (UFW, firewalld, or iptables)
• Opens required ports (80, 443, 4096)
• Maintains existing firewall rules
• Ensures secure access

6. Service Activation

• Enables Vector to start on boot
• Starts the Vector service
• Verifies everything is running correctly

7. Validation

• Tests WebSocket server is listening
• Verifies TLS certificates are valid
• Provides connection URL for Actvt
• Displays next steps

Prerequisites

Before running the installation script, ensure you have:

• Linux Server: Ubuntu 20.04+, Debian 10+, CentOS 7+, or Amazon Linux 2
• Root Access: The script must be run as root or with sudo
• Domain Name: A domain pointing to your server's public IP (e.g., monitor.yourdomain.com)
• DNS Configured: A record resolving to your server's IP address
• Port Access: Ports 80, 443, and 4096 must be accessible
• Internet Connection: Required for downloading packages

Interactive Prompts

During installation, the script will ask for:

Domain Name

Enter your domain name (e.g., monitor.yourdomain.com):
>

This is required for obtaining TLS certificates. Make sure your domain's DNS is configured before running the script.

Email Address (Optional)

Enter your email for Let's Encrypt notifications (optional):
>

Let's Encrypt will send renewal reminders to this email. You can skip this by pressing Enter.

GPU Monitoring (If Detected)

Enable GPU monitoring? [Y/n]
>

If an NVIDIA GPU is detected, you'll be asked if you want to enable GPU metrics collection.

Vector Reinstallation (If Already Installed)

Do you want to reinstall/update Vector? [y/N]
>

If Vector is already installed, you can choose to skip reinstallation or update to the latest version.

Non-Interactive Installation

For automated deployments, CI/CD pipelines, or infrastructure-as-code, you can provide all configuration via environment variables. The script will automatically run in non-interactive mode when piped from curl.

Available Environment Variables

Variable	Description	Default	Required
ACTVT_DOMAIN	Server domain name	-	Yes
ACTVT_EMAIL	Let's Encrypt email for renewal notifications	-	Non-interactive only
ACTVT_INSTALL_MODE	Installation mode: auto (detect), standalone, or proxy	auto	No
ACTVT_VECTOR_PORT	Vector WebSocket port	4096	No
ACTVT_NGINX_WEBROOT	Webroot for Certbot http-01 in proxy mode	/var/www/html	No
ACTVT_FORCE_STANDALONE	Force standalone mode even if nginx is detected	no	No
ACTVT_REINSTALL_VECTOR	Reinstall Vector if already installed	no	No
ACTVT_ENABLE_GPU	Enable GPU monitoring if GPU detected	yes	No
ACTVT_REUSE_CERT	Reuse existing certificates if present	yes	No
ACTVT_CONTINUE_WITHOUT_DNS	Continue if DNS resolution fails	no	No
ACTVT_CONFIGURE_FIREWALL	Configure firewall rules (UFW/firewalld/iptables)	yes	No
ACTVT_ENABLE_MTLS	Enable mTLS client certificate verification	no	No
ACTVT_MTLS_CA_DAYS	CA certificate validity in days	3650 (10 years)	No
ACTVT_MTLS_CLIENT_DAYS	Client certificate validity in days	365 (1 year)	No
ACTVT_MTLS_CLIENT_CN	Client certificate common name	actvt-client-001	No
ACTVT_REUSE_MTLS_CA	Reuse existing mTLS CA certificate	yes	No
ACTVT_REGEN_CLIENT_CERT	Regenerate client certificate	no	No
ACTVT_NON_INTERACTIVE	Force non-interactive mode	auto-detect	No

Basic Non-Interactive Installation

Minimal installation with just the required variables:

export ACTVT_DOMAIN="monitor.yourdomain.com"
export ACTVT_EMAIL="[email protected]"
curl -L https://actvt.io/install | bash

Or as a one-liner:

ACTVT_DOMAIN="monitor.yourdomain.com" ACTVT_EMAIL="[email protected]" curl -L https://actvt.io/install | bash

Complete Non-Interactive Installation

Full control over all settings:

export ACTVT_DOMAIN="monitor.yourdomain.com"
export ACTVT_EMAIL="[email protected]"
export ACTVT_REINSTALL_VECTOR="no"
export ACTVT_ENABLE_GPU="yes"
export ACTVT_REUSE_CERT="yes"
export ACTVT_CONTINUE_WITHOUT_DNS="no"
curl -L https://actvt.io/install | bash

Force Reinstall Scenario

If you want to reinstall Vector and get new certificates:

export ACTVT_DOMAIN="monitor.yourdomain.com"
export ACTVT_REINSTALL_VECTOR="yes"
export ACTVT_REUSE_CERT="no"
curl -L https://actvt.io/install | bash

Development/Testing Without DNS

For testing environments where DNS is not configured:

export ACTVT_DOMAIN="test.internal"
export ACTVT_CONTINUE_WITHOUT_DNS="yes"
curl -L https://actvt.io/install | bash

Warning: Certificate acquisition will fail without proper DNS. This is only suitable for testing.

Cloud Environments (AWS/Azure/GCP)

For cloud environments where firewall is managed via Security Groups, Network Security Groups, or Cloud Firewall:

# Skip firewall configuration since it's managed by cloud provider
export ACTVT_DOMAIN="monitor.example.com"
export ACTVT_EMAIL="[email protected]"
export ACTVT_CONFIGURE_FIREWALL="no"
curl -L https://actvt.io/install | bash

Note: Ensure your cloud security groups allow inbound traffic on ports 80, 443, and 4096.

mTLS (Mutual TLS) Installation

For enhanced security with client certificate authentication:

export ACTVT_DOMAIN="monitor.yourdomain.com"
export ACTVT_EMAIL="[email protected]"
export ACTVT_ENABLE_MTLS=yes
curl -L https://actvt.io/install | bash

With custom certificate validity periods:

export ACTVT_DOMAIN="monitor.yourdomain.com"
export ACTVT_EMAIL="[email protected]"
export ACTVT_ENABLE_MTLS=yes
export ACTVT_MTLS_CA_DAYS=7300          # CA valid for 20 years
export ACTVT_MTLS_CLIENT_DAYS=730       # Client cert valid for 2 years
export ACTVT_MTLS_CLIENT_CN="my-laptop"
curl -L https://actvt.io/install | bash

After installation, download the client certificate bundle:

# On the server, make bundle accessible
sudo chmod 644 /etc/vector/certs/mtls/actvt-client-001-bundle.tar.gz

# Download to your Mac
scp [email protected]:/etc/vector/certs/mtls/actvt-client-001-bundle.tar.gz ~/Downloads/

# Extract certificates
cd ~/Downloads
tar -xzf actvt-client-001-bundle.tar.gz

See the mTLS Security Guide for complete setup and usage instructions.

What Gets Installed

• Vector — data pipeline with systemd service
• Certbot — Let's Encrypt client with auto-renewal deploy hook
• /etc/vector/vector.toml — Vector configuration
• /etc/vector/certs/ — TLS certificates (copied from Let's Encrypt)
• /var/lib/actvt/ — installation state and backups (see State Management)

Troubleshooting

Script Fails to Download

If you see curl: (6) Could not resolve host:

# Check internet connectivity
ping -c 4 8.8.8.8

# Check DNS resolution
nslookup actvt.io

Permission Denied

The script must be run as root or with sudo:

# Use sudo if you're not root
sudo bash -c "$(curl -L https://actvt.io/install)"

Certificate Acquisition Fails

Common causes:

• Port 80 is not accessible from the internet
• DNS has not propagated yet
• Firewall blocking Let's Encrypt validation

# Verify port 80 is accessible
sudo netstat -tlnp | grep :80

# Check DNS resolution
dig yourdomain.com

# Wait up to 24 hours for DNS propagation

Vector Service Won't Start

Check the logs for specific errors:

# View Vector logs
sudo journalctl -u vector -n 50

# Check configuration
sudo vector validate /etc/vector/vector.toml

# Check certificate permissions
ls -la /etc/vector/certs/

Installation Log

If installation fails, check the detailed log:

# View installation log
sudo tail -n 100 /var/log/actvt-install.log

# Or use less for full log
sudo less /var/log/actvt-install.log

Security Considerations

Script Safety

The curl | bash pattern is commonly used but carries risks. To verify the script before running:

# Download and inspect the script first
curl -L https://actvt.io/install > install.sh
less install.sh

# Run it manually after inspection
sudo bash install.sh

What the Script Does NOT Do

The script will NOT:

• Modify SSH configuration
• Change user passwords
• Access sensitive files
• Install unnecessary packages
• Open ports beyond 80, 443, and 4096
• Send data to external services (except Let's Encrypt for certificates)

TLS Certificate Security

• Certificates are automatically renewed before expiration
• Certificates are copied into /etc/vector/certs with restrictive permissions
  • server.crt: 644 vector:vector
  • server.key: 640 vector:vector
• A Certbot deploy hook refreshes these files on renewal and reloads Vector (and nginx if present)

Nginx Reverse Proxy and Snippet Include

When nginx is already serving your domain on port 443, the installer avoids creating a conflicting server block. Instead, it creates a snippet you include in your existing server block:

1. Snippet location:

/etc/nginx/snippets/actvt-vector-location.conf

2. Include it inside the existing server for your domain:

server {
    listen 443 ssl http2;
    server_name monitor.yourdomain.com;
    # ... your existing config ...

    include /etc/nginx/snippets/actvt-vector-location.conf;
}

3. Test and reload nginx:

sudo nginx -t && sudo systemctl reload nginx

If no existing server block is found, the installer creates and enables a dedicated server block at /etc/nginx/sites-available/actvt-vector.

Managing the Installation

For service management commands, see Vector Setup — Managing Vector. For certificate renewal, see TLS Configuration — Auto-Renewal.

Uninstalling

To completely remove the installation:

# Stop and disable Vector service
sudo systemctl stop vector
sudo systemctl disable vector

# Remove Vector package
# Ubuntu/Debian:
sudo apt-get remove --purge vector

# CentOS/RHEL/Amazon Linux:
sudo yum remove vector

# Remove configuration and state files
sudo rm -rf /etc/vector
sudo rm -rf /var/lib/actvt
sudo rm -f /var/log/actvt-install.log

# Optional: Remove Let's Encrypt certificates
sudo certbot delete --cert-name yourdomain.com

Next Steps

After successful installation:

1. Open Actvt: Launch the Actvt application on your Mac
2. Add Server: Go to Settings → Remote Servers
3. Enter URL: Use the WebSocket URL provided
   • Proxy mode: wss://monitor.yourdomain.com/actvt
   • Standalone: wss://monitor.yourdomain.com:4096
4. Connect: Click "Add Server" or "Connect"
5. Monitor: Start viewing real-time metrics from your remote server!

Support

If you encounter any issues:

• Documentation: See the Troubleshooting Guide
• Manual Installation: Try the step-by-step guide if automated installation fails
• Logs: Check /var/log/actvt-install.log for detailed error messages
• Service Logs: Use journalctl -u vector -f to view Vector logs

The automated installation script is designed to work on most standard server configurations. If you have a custom setup or encounter issues, the manual installation process provides more control and troubleshooting options.