---
name: static-site-deploy
description: |-
  Deploy, download, and browse static HTML sites on VPS via FTP.
triggers:
  - deploy static site
  - deploy html
  - deploy to vps
  - static deploy
  - download from vps
  - list files on vps
  - browse ftp
  - read file from vps
  - 部署静态网站
  - 部署HTML
  - 部署到VPS
  - 从服务器下载
  - 浏览服务器文件
  - 读取服务器文件
category: Web Services
---

# Static Site Deploy

Upload, download, read, and browse static HTML files on a VPS via FTP.

## Use when

- Deploying static HTML/CSS/JS files to a VPS
- Downloading deployed files from VPS
- Reading file contents directly from VPS (without downloading to local)
- Browsing files and directories on VPS
- Publishing a single-page app, landing page, or documentation site
- User says "deploy", "upload to server", "publish site", "download from server", "read file", or "list files"

## Prerequisites

- ASSISTANT_ID environment variable must be set (bot_id)
- Deployment script configured with FTP credentials

## Deployment Workflow

### Phase 1: Prepare

1. Identify the source directory (e.g., `./dist/`, `./build/`, `./public/`, or user-specified)
2. Determine `project-name`:
   - From user input, OR
   - From the source directory's parent folder name
3. Verify ASSISTANT_ID environment variable is set

### Phase 2: Deploy

Execute the deploy script:

```bash
# Basic usage
bash scripts/deploy.sh <source-dir> <project-name>

# With custom config
bash scripts/deploy.sh <source-dir> <project-name>  --config /path/to/config.yml

# Dry run (preview without uploading)
bash scripts/deploy.sh <source-dir> <project-name> --dry-run
```

The script will:
- Upload files to VPS
- Show deployment summary and progress
- Verify deployment via FTP and HTTP checks

### Phase 3: Verify

The script automatically verifies:
1. **FTP verification** - confirms files are present on server
2. **HTTP verification** - confirms site is accessible (expects HTTP 200)

Final output shows:
```
=== Deploy Complete ===
URL: https://domain/path/to/deploy/
```

## Error Handling

| Error | Detection | Fix |
|-------|-----------|-----|
| FTP connection refused | curl returns "connection refused" | Check FTP service is running, verify port |
| FTP auth failed | curl returns 530 | Check username/password in config |
| Upload permission denied | curl returns 553 | Check FTP user write permission on web_root |
| HTTP 404 | curl returns 404 | Confirm Nginx root matches FTP upload path |
| HTTP 403 | curl returns 403 | Fix permissions: files 644, directories 755 |

## Implementation Notes

- Use `scripts/deploy.sh` for uploading files to VPS
- Use `scripts/download.sh` for downloading files from VPS
- Use `scripts/list.sh` for browsing FTP directory contents
- Use `scripts/read.sh` for reading file contents directly from FTP (output to stdout)
- Verify ASSISTANT_ID environment variable is set before calling scripts
- Show the command to the user before executing
- The scripts handle all FTP operations, progress display, and verification

## List Files Workflow

To browse files on VPS:

```bash
# List all projects under bot directory
bash scripts/list.sh

# List files in a specific project
bash scripts/list.sh <project-name>
```

The list script will:
- Read bot_id from ASSISTANT_ID environment variable
- Show directory contents from `/{bot_id}/` or `/{bot_id}/{project_name}/`
- Mark directories with trailing `/`
- Only list current directory level (non-recursive)

## Download Workflow

To download files from VPS:

```bash
# Basic usage
bash scripts/download.sh <project-name> <target-dir>

# With custom config
bash scripts/download.sh <project-name> <target-dir> --config /path/to/config.yml
```

The download script will:
- Read bot_id from ASSISTANT_ID environment variable
- Download files from `/{bot_id}/{project_name}/`
- Save to the specified target directory
- Show download summary and file count

## Read File Workflow

To read a file's content directly from VPS (output to stdout, no local download):

```bash
# Read a file from a project
bash scripts/read.sh <project-name>/<path/to/file.html>

# With custom config
bash scripts/read.sh <project-name>/index.html --config /path/to/config.yml
```

The read script will:
- Read bot_id from ASSISTANT_ID environment variable
- Fetch the file from `/{bot_id}/{file-path}` via FTP
- Output file contents directly to stdout