wasm-cli 0.11.4

Web App System Management - Deploy and manage web applications on Linux servers

WASM - Web App System Management

Deploy, manage, and monitor web applications with ease

Installation • Quick Start • Features • Documentation

---

🚀 What is WASM?

WASM (Web App System Management) is a powerful CLI tool designed to simplify the deployment and management of web applications on Linux servers. It automates the entire process from cloning your code to serving it with Nginx/Apache, including SSL certificates and systemd services.

Key Capabilities

• 🌐 Site Management - Create and manage Nginx/Apache virtual hosts
• 🔒 SSL Certificates - Automated Let's Encrypt certificates via Certbot
• ⚙️ Service Management - Create and control systemd services
• 🚀 One-Command Deployment - Deploy full-stack applications instantly
• 🎯 Multi-Framework Support - Next.js, Node.js, Vite, Python, and more
• 🧭 Interactive Mode - Guided step-by-step deployment wizard

---

📦 Installation

Ubuntu/Debian - From OBS Repository (Recommended)

# Add repository key
curl -fsSL https://download.opensuse.org/repositories/home:/Perkybeet/xUbuntu_24.04/Release.key | \
  gpg --dearmor | sudo tee /usr/share/keyrings/wasm.gpg > /dev/null

# Add repository (Ubuntu 24.04)
echo 'deb [signed-by=/usr/share/keyrings/wasm.gpg] https://download.opensuse.org/repositories/home:/Perkybeet/xUbuntu_24.04/ /' | \
  sudo tee /etc/apt/sources.list.d/wasm.list

# Install
sudo apt update
sudo apt install wasm

Supported Ubuntu versions:

• Ubuntu 22.04 LTS (Jammy Jellyfish)
• Ubuntu 24.04 LTS (Noble Numbat)

Fedora - From OBS Repository

# Add repository
sudo dnf config-manager --add-repo \
  https://download.opensuse.org/repositories/home:/Perkybeet/Fedora_40/home:Perkybeet.repo

# Install
sudo dnf install wasm-cli

openSUSE - From OBS Repository

# Tumbleweed
sudo zypper ar -f \
  https://download.opensuse.org/repositories/home:/Perkybeet/openSUSE_Tumbleweed/ \
  home_Perkybeet
sudo zypper install wasm-cli

# Leap 15.6
sudo zypper ar -f \
  https://download.opensuse.org/repositories/home:/Perkybeet/openSUSE_Leap_15.6/ \
  home_Perkybeet
sudo zypper install wasm-cli

Debian - From OBS Repository

# Add repository key
curl -fsSL https://download.opensuse.org/repositories/home:/Perkybeet/Debian_12/Release.key | \
  gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/home_Perkybeet.gpg > /dev/null

# Add repository
echo 'deb https://download.opensuse.org/repositories/home:/Perkybeet/Debian_12/ /' | \
  sudo tee /etc/apt/sources.list.d/home_Perkybeet.list

# Install
sudo apt update
sudo apt install wasm-cli

From .deb Package

wget https://github.com/Perkybeet/wasm/releases/latest/download/wasm_0.8.2_all.deb
sudo dpkg -i wasm_0.8.2_all.deb
sudo apt install -f  # Install dependencies if needed

From PyPI

pip install wasm-cli

From Source

git clone https://github.com/Perkybeet/wasm.git
cd wasm
pip install -e .

---

🏃 Quick Start

Deploy a Next.js Application

# One-liner deployment
wasm webapp create \
  --domain myapp.example.com \
  --source [e-mail]:user/my-nextjs-app.git \
  --type nextjs \
  --port 3000

# Short version
wasm wp create -d myapp.example.com -s [e-mail]:user/app.git -t nextjs -p 3000

Interactive Mode

For a guided experience, simply run:

wasm

Or explicitly:

wasm --interactive

You'll be guided through all the options step by step:

┌─────────────────────────────────────────────────┐
│           WASM - Web App System Management      │
└─────────────────────────────────────────────────┘

? What would you like to do?
❯ 🚀 Deploy a Web Application
  🌐 Manage Sites (Nginx/Apache)
  ⚙️  Manage Services
  🔒 Manage SSL Certificates
  📊 View Status Dashboard
  ⚡ Exit

? Select application type:
❯ Next.js
  Node.js (Express, Fastify, etc.)
  Vite (React, Vue, Svelte)
  Python (Django, Flask, FastAPI)
  Static Site
  Custom

? Enter the domain name: myapp.example.com
? Enter the source (Git URL or path): [e-mail]:user/app.git
? Enter the port number: 3000
? Configure SSL certificate? Yes

[1/7] 📥 Cloning repository...
[2/7] 📦 Installing dependencies...
[3/7] 🔨 Building application...
[4/7] 🌐 Creating Nginx configuration...
[5/7] 🔒 Obtaining SSL certificate...
[6/7] ⚙️  Creating systemd service...
[7/7] 🚀 Starting application...

✅ Deployment complete!

   URL: https://myapp.example.com
   Status: Running
   Service: wasm-myapp-example-com

---

📋 Features

Web Application Deployment

# Create a new web application
wasm webapp create [options]

Options:
  -d, --domain DOMAIN     Target domain (e.g., example.com)
  -s, --source SOURCE     Git URL or local path to source code
  -t, --type TYPE         Application type (nextjs, nodejs, vite, python, static)
  -p, --port PORT         Application port (default: auto-assigned)
  -w, --webserver SERVER  Web server (nginx, apache) [default: nginx]
  --no-ssl                Skip SSL certificate configuration
  --branch BRANCH         Git branch to deploy [default: main]
  --env-file FILE         Path to .env file to use
  -v, --verbose           Enable verbose output

# List deployed applications
wasm webapp list

# Get application status
wasm webapp status myapp.example.com

# Restart application
wasm webapp restart myapp.example.com

# Remove application
wasm webapp delete myapp.example.com

# Update application (pull & rebuild)
wasm webapp update myapp.example.com

Site Management

# Create a site (without deploying an app)
wasm site create -d example.com -w nginx

# List all sites
wasm site list

# Enable/disable site
wasm site enable example.com
wasm site disable example.com

# Delete site
wasm site delete example.com

# Show site configuration
wasm site show example.com

Service Management

# Create a custom service
wasm service create --name myservice --command "/usr/bin/myapp" --user www-data

# List managed services
wasm service list

# Control services
wasm service start myservice
wasm service stop myservice
wasm service restart myservice

# View service status
wasm service status myservice

# View service logs
wasm service logs myservice
wasm service logs myservice --follow
wasm service logs myservice --lines 100

# Delete service
wasm service delete myservice

SSL Certificate Management

# Obtain certificate for a domain
wasm cert create -d example.com

# List certificates
wasm cert list

# Renew all certificates
wasm cert renew

# Revoke a certificate
wasm cert revoke example.com

# Show certificate info
wasm cert info example.com

---

🎯 Supported Application Types

Type	Framework	Auto-Detection
nextjs	Next.js	next.config.js
nodejs	Express, Fastify, Koa, etc.	package.json with start script
vite	React, Vue, Svelte (Vite)	vite.config.js
python	Django, Flask, FastAPI	requirements.txt, pyproject.toml
static	HTML/CSS/JS	index.html

Each type has a specific deployment workflow that includes:

• Dependency installation
• Build process
• Environment configuration
• Service setup
• Health checks

---

⚙️ Configuration

Global Configuration

Configuration file location: /etc/wasm/config.yaml

# Default web server
webserver: nginx

# Default apps directory
apps_directory: /var/www/apps

# Default user for services
service_user: www-data

# SSL settings
ssl:
  enabled: true
  provider: certbot
  email: [e-mail]
  
# Logging
logging:
  level: info
  file: /var/log/wasm/wasm.log

# Node.js settings
nodejs:
  default_version: 20
  use_nvm: false

# Python settings
python:
  default_version: "3.11"
  use_venv: true

Per-Project Configuration

You can include a .wasm.yaml file in your project root:

type: nextjs
port: 3000
build_command: npm run build
start_command: npm run start
env_vars:
  NODE_ENV: production
health_check:
  path: /api/health
  timeout: 30

---

📊 Verbose Mode

Add --verbose or -v for detailed output:

wasm webapp create -d example.com -s [e-mail]:user/app.git -t nextjs -v

Verbose output example:

[1/7] 📥 Cloning repository...
      ├─ Source: [e-mail]:user/app.git
      ├─ Branch: main
      ├─ Target: /var/www/apps/example-com
      └─ Completed in 4.2s

[2/7] 📦 Installing dependencies...
      ├─ Package manager: npm
      ├─ Command: npm ci --production=false
      ├─ Packages installed: 1,247
      └─ Completed in 45.3s

[3/7] 🔨 Building application...
      ├─ Command: npm run build
      ├─ Output directory: .next
      ├─ Build size: 12.4 MB
      └─ Completed in 32.1s
...

---

🗂️ Directory Structure

WASM organizes deployed applications as follows:

/var/www/apps/
├── example-com/
│   ├── current/          # Current deployment (symlink)
│   ├── releases/         # Previous releases (for rollback)
│   │   ├── 20241215120000/
│   │   └── 20241214150000/
│   ├── shared/           # Shared files (uploads, logs)
│   └── .env              # Environment variables
│
└── another-app/
    └── ...

---

🔧 Requirements

System Requirements

• OS: Ubuntu 20.04+, Debian 11+
• Python: 3.10+
• Privileges: sudo access for service management

Optional Dependencies

• nginx or apache2 - Web server
• certbot - SSL certificates
• git - Source code management
• nodejs / nvm - For Node.js applications
• python3-venv - For Python applications

WASM will check and prompt for missing dependencies during installation.

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

# Development setup
git clone https://github.com/Perkybeet/wasm.git
cd wasm
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Build and upload to OBS (all distributions)
make obs-upload

# Check OBS build status
make obs-status

For detailed information about building and uploading to OBS, see docs/OBS_SETUP.md.

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Certbot for SSL automation
• python-inquirer for interactive CLI
• The open-source community

---

Made with ❤️ for the DevOps community