shipfe 1.1.1 → 1.1.3

package/docs/config/sub-env.md

@@ -1,62 +0,0 @@
-# Sub-environments
-
-Sub-environments allow deploying multiple applications or different configurations on the same server.
-
-## Configuration Structure
-
-```json
-{
-  "environments": {
-    "dev": {
-      "build_command": "npm run build",
-      "local_dist_path": "./dist",
-      "servers": [...],
-      "sub_environments": {
-        "admin": {
-          "build_command": "npm run build:admin",
-          "remote_deploy_path": "/var/www/dev/admin"
-        },
-        "shop": {
-          "build_command": "npm run build:shop",
-          "remote_deploy_path": "/var/www/dev/shop"
-        }
-      }
-    }
-  }
-}
-```
-
-## Inheritance Rules
-
-Sub-environments inherit all settings from their parent environment but can override:
-
-- `build_command`
-- `local_dist_path`
-- `remote_deploy_path`
-
-## Deploying Sub-environments
-
-```bash
-# Deploy single sub-environment
-shipfe deploy --profile dev-admin
-shipfe deploy --profile dev-shop
-
-# Deploy all sub-environments
-shipfe deploy --profile dev --all-sub
-```
-
-## Directory Structure
-
-Parent and sub-environments are deployed to different directories:
-
-```
-/var/www/dev/          # Parent environment
-/var/www/dev/admin/    # Sub-environment admin
-/var/www/dev/shop/     # Sub-environment shop
-```
-
-## Rolling Back Sub-environments
-
-```bash
-shipfe rollback --profile dev-admin --to 20260303_034945
-```

package/docs/features/atomic.md

@@ -1,67 +0,0 @@
-# Atomic Deployment
-
-Atomic deployment enables zero-downtime deployment through symbolic link switching for consistency.
-
-## How It Works
-
-When using `--atomic`, deployment:
-
-1. Creates a timestamped release directory: `releases/20260303_034945/`
-2. Uploads files to the new directory
-3. Updates the `current` symbolic link to point to the new directory
-
-## Directory Structure
-
-```
-remote_deploy_path/
-├── releases/
-│   ├── 20260303_034945/
-│   ├── 20260303_035012/
-│   └── 20260303_035045/
-└── current -> releases/20260303_035045
-```
-
-## Web Server Configuration
-
-Your web server should serve from `remote_deploy_path/current`.
-
-### Nginx Example
-
-```nginx
-server {
-    listen 80;
-    server_name your-domain.com;
-    root /var/www/prod/current;
-    index index.html;
-    
-    location / {
-        try_files $uri $uri/ =404;
-    }
-}
-```
-
-### Apache Example
-
-```apache
-<VirtualHost *:80>
-    ServerName your-domain.com
-    DocumentRoot /var/www/prod/current
-</VirtualHost>
-```
-
-## Benefits
-
-- **Zero Downtime**: Switching happens instantly
-- **Atomicity**: Either everything succeeds or everything fails
-- **Instant Rollback**: Just change the symbolic link
-- **Version Isolation**: Each release is stored independently
-
-## Usage
-
-```bash
-# Atomic deployment to default environment
-shipfe deploy --atomic
-
-# Atomic deployment to specified environment
-shipfe deploy --profile prod --atomic
-```

package/docs/features/cleanup.md

@@ -1,80 +0,0 @@
-# Automatic Cleanup
-
-Shipfe provides configurable automatic cleanup of old releases and unused shared resources.
-
-## Configuration Options
-
-### `keep_releases` (Recommended)
-
-```json
-{
-  "keep_releases": 5,
-  "delete_old": false
-}
-```
-
-- Keep the most recent 5 releases
-- Automatically delete old releases
-- Works with shared resource cleanup
-
-### `delete_old` (Legacy)
-
-```json
-{
-  "delete_old": true
-}
-```
-
-- Delete all old releases after each deployment
-- Keep only the current deployment
-- Overrides `keep_releases` setting
-
-## Cleanup Process
-
-### Release Cleanup
-
-1. Sort releases by modification time (newest first)
-2. Keep the specified number of recent releases
-3. Completely delete old release directories
-
-### Shared Resource Cleanup (when `enable_shared: true`)
-
-1. Scan all remaining release snapshots
-2. Collect all currently referenced hashed resources
-3. Delete unreferenced files from `shared/assets/`
-
-## Cleanup Behavior Example
-
-### Before Cleanup (7 releases)
-
-```
-releases/
-├── 20260301_100000/  (oldest)
-├── 20260302_100000/
-├── 20260303_100000/
-├── 20260304_100000/
-├── 20260305_100000/
-├── 20260306_100000/
-└── 20260307_100000/  (newest, current)
-```
-
-### After Cleanup (`keep_releases: 3`)
-
-```
-releases/
-├── 20260305_100000/  (kept)
-├── 20260306_100000/  (kept)
-└── 20260307_100000/  (kept, current)
-```
-
-*Old releases automatically deleted*
-
-## Monitoring Cleanup
-
-```bash
-# Check current releases
-ls -la releases/
-
-# View cleanup logs in shipfe.log
-tail -f shipfe.log | grep -i "cleanup\|remove"
-```

package/docs/features/shared-assets.md

@@ -1,72 +0,0 @@
-# Shared Assets
-
-Shared assets reduce disk usage and network transmission through file hash deduplication.
-
-## Enable Shared Assets
-
-```json
-{
-  "enable_shared": true,
-  "hashed_asset_patterns": [
-    "**/*.js",
-    "**/*.css",
-    "**/*.png",
-    "**/*.jpg",
-    "**/*.svg",
-    "**/*.woff2"
-  ]
-}
-```
-
-## How It Works
-
-1. **File Matching**: Matches files according to `hashed_asset_patterns`
-2. **Hash Calculation**: Calculates SHA256 hash for matching files
-3. **Storage Strategy**:
-   - Same hash files are stored only once in `shared/assets/` directory
-   - Filename format: `{hash}.{ext}`, e.g., `abc123def456.js`
-4. **Link Creation**: Creates hard links in release directory pointing to shared files
-5. **Cleanup Mechanism**: Deletes shared files no longer referenced by any release
-
-## Shared Assets Reset
-
-At the start of each deployment, Shipfe automatically clears all existing resources in the `shared/` directory and recreates the `shared/assets/` directory. This ensures each deployment starts from a clean state, avoiding accumulation of old resources and potential conflicts.
-
-## Directory Structure Example
-
-```
-remote_deploy_path/
-├── shared/
-│   └── assets/
-│       ├── abc123def456.js
-│       ├── def789ghi012.css
-│       └── hij345klm678.png
-├── releases/
-│   ├── 20260304_120000/
-│   │   ├── index.html
-│   │   ├── app.js -> ../../shared/assets/abc123def456.js
-│   │   └── styles.css -> ../../shared/assets/def789ghi012.css
-│   └── 20260304_120100/
-│       ├── index.html
-│       ├── app.js -> ../../shared/assets/abc123def456.js
-│       └── styles.css -> ../../shared/assets/def789ghi012.css
-└── current -> releases/20260304_120100
-```
-
-## Benefits
-
-- **Reduced Disk Usage**: Same files stored only once
-- **Faster Deployments**: Unchanged files don't need re-uploading
-- **Bandwidth Savings**: Only new or changed files are transmitted
-- **Atomic Updates**: All hard links created simultaneously for consistency
-
-## Notes
-
-- Shared assets require hard link support on the server filesystem
-- First enablement hashes all matching files
-- Disabling shared doesn't delete existing shared files; manual cleanup required
-
-## Use Cases
-
-- **Enable Shared**: Large apps with frequent deployments and many static resources
-- **Disable Shared**: Small apps with infrequent deployments or need for simple debugging

package/docs/features/snapshot.md

@@ -1,58 +0,0 @@
-# Resource Snapshots
-
-Each deployment generates a snapshot containing a complete file manifest for auditing and rollback verification.
-
-## Snapshot Contents
-
-- All deployed files and their hashes
-- Shared resource references
-- Deployment timestamp and metadata
-- File permissions and size information
-
-## Snapshot File Location
-
-```
-releases/20260304_120100/
-├── files/
-│   ├── index.html
-│   └── app.js -> ../../shared/assets/abc123def456.js
-├── snapshot.json
-└── metadata.json
-```
-
-## snapshot.json Example
-
-```json
-{
-  "timestamp": "20260304_120100",
-  "files": {
-    "index.html": {
-      "hash": "a1b2c3d4e5f6...",
-      "size": 1024,
-      "permissions": "644"
-    },
-    "app.js": {
-      "shared_hash": "abc123def456.js",
-      "size": 51200,
-      "permissions": "644"
-    }
-  }
-}
-```
-
-## metadata.json Example
-
-```json
-{
-  "build_command": "npm run build",
-  "deployed_by": "user",
-  "deployed_at": "2026-03-04T12:01:00Z"
-}
-```
-
-## 用途
-
-- **审计**：验证部署内容
-- **回滚验证**：确保回滚到正确版本
-- **清理**：确定哪些共享资源可以删除
-- **调试**：排查部署问题

package/docs/index.md

@@ -1,48 +0,0 @@
-# Shipfe
-
-[![npm version](https://img.shields.io/npm/v/shipfe.svg)](https://www.npmjs.com/package/shipfe)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![GitHub](https://img.shields.io/badge/GitHub-Master--Jian/shipfe--rust-blue.svg)](https://github.com/Master-Jian/shipfe-rust)
-
-A powerful, **free**, **Rust-based** web app deployment tool that **doesn't request network**, enabling **one-click static frontend package uploads to servers**. Supports multi-environment and sub-environment deployments with zero-downtime atomic deployment functionality.
-
-## Key Features
-
-- 🚀 **Free & Open Source**: No hidden fees, MIT license
-- 🦀 **Rust-Based**: Fast, reliable, memory-safe
-- 🔒 **No Network Requests**: Works completely offline, ensuring security and privacy
-- ⚡ **One-Click Deployment**: Instantly upload static frontend packages to servers
-- 🔄 **Atomic Deployment**: Zero-downtime deployment with automatic rollback
-- 🌍 **Multi-Environment Support**: Configure different environments (dev, staging, prod)
-- 📦 **Sub-Environment Support**: Deploy multiple apps on the same server
-- 🔑 **Flexible Authentication**: SSH keys, passwords, or environment variables
-- 📝 **Detailed Logging**: Comprehensive deployment logs for troubleshooting
-- 🗂️ **Shared Resource Management**: Cross-release deduplication of hashed static resources
-- 📊 **Resource Snapshots**: Generate snapshots with file manifests for deployment auditing
-- 🧹 **Automatic Cleanup**: Configurable old release retention and unused resource cleanup
-- 🗑️ **Shared Resource Reset**: Automatically clears all shared resources during deployment for clean deployments
-
-## Installation
-
-[Installation Guide](/install)
-
-## Quick Start
-
-1. Initialize project:
-```bash
-shipfe init
-```
-
-2. Configure deployment in `shipfe.config.json`
-
-3. Deploy:
-```bash
-shipfe deploy --profile prod
-```
-
-## Quick Links
-
-- [Quick Start](/quick-start)
-- [Config Overview](/config/overview)
-- [Deploy Command](/commands/deploy)
-- [Rollback Command](/commands/rollback)

package/docs/install.md

@@ -1,21 +0,0 @@
-# Installation
-
-## npm Installation
-
-```bash
-npm install -g shipfe
-```
-
-## Verify Installation
-
-Check version:
-
-```bash
-shipfe --version
-```
-
-View help:
-
-```bash
-shipfe --help
-```

package/docs/license.md

@@ -1,23 +0,0 @@
-# License
-
-MIT License
-
-Copyright (c) 2024 Master-Jian
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/docs/quick-start.md

@@ -1,98 +0,0 @@
-# Quick Start
-
-This page aims to complete a full deployment cycle (init → config → deploy → verify → rollback) with minimal configuration.
-
-## 1. Installation
-
-```bash
-npm install -g shipfe
-shipfe --version
-```
-
-## 2. Initialize Configuration
-
-Run in your project root directory:
-
-```bash
-shipfe init
-```
-
-This will generate (example):
-
-```
-shipfe.config.json
-```
-
-## 3. Write a Minimal Viable Configuration (Single Server, Single Environment)
-
-Edit `shipfe.config.json`:
-
-```json
-{
-  "keep_releases": 5,
-  "environments": {
-    "prod": {
-      "build_command": "npm run build",
-      "local_dist_path": "./dist",
-      "remote_tmp": "/tmp",
-      "servers": [
-        {
-          "host": "YOUR_SERVER_IP",
-          "port": 22,
-          "username": "deploy",
-          "remote_deploy_path": "/var/www/shipfe-demo"
-        }
-      ]
-    }
-  }
-}
-```
-
-## 4. First Deployment (Atomic Deployment Recommended)
-
-```bash
-shipfe deploy --profile prod --atomic
-```
-
-After deployment, the server directory will typically be:
-
-```
-/var/www/shipfe-demo/
-  releases/
-    20260304_120100/
-  current -> releases/20260304_120100
-```
-
-Your Nginx/static server should serve from:
-
-```
-/var/www/shipfe-demo/current
-```
-
-## 5. Verify Deployment
-
-Check on the server:
-
-```bash
-ls -la /var/www/shipfe-demo
-ls -la /var/www/shipfe-demo/current
-```
-
-Or directly access your domain/server address.
-
-## 6. Rollback to a Specific Version
-
-Rollback to a specific timestamp version (example):
-
-```bash
-shipfe rollback --profile prod --to 20260303_034945
-```
-
-Timestamps come from the `releases/` directory names.
-
-## Next Steps
-
-- Config details: [/config/overview](/config/overview)
-- Deploy command parameters: [/commands/deploy](/commands/deploy)
-- Atomic deployment principles: [/features/atomic](/features/atomic)
-- Shared asset management: [/features/shared-assets](/features/shared-assets)

package/docs/troubleshooting.md

@@ -1,88 +0,0 @@
-# Troubleshooting
-
-## Common Issues
-
-### 1. Permission Denied Error
-
-```
-Error: Permission denied (publickey)
-```
-
-**Solutions:**
-- Verify SSH key is added to server's `~/.ssh/authorized_keys`
-- Check SSH key permissions: `chmod 600 ~/.ssh/id_rsa`
-- Test SSH connection: `ssh user@host`
-
-### 2. Shared Resources Not Working
-
-```
-Warning: Failed to create hard link for shared asset
-```
-
-**Solutions:**
-- Ensure `enable_shared: true` in configuration
-- Check if server filesystem supports hard links
-- Verify write permissions for shared directory
-
-### 3. Cleanup Not Working
-
-```
-Warning: Failed to remove old release
-```
-
-**Solutions:**
-- Check file permissions in releases directory
-- Ensure no processes are using old release files
-- Verify `keep_releases` setting is correct
-
-### 4. Snapshot Creation Failed
-
-```
-Error: Failed to create snapshot
-```
-
-**Solutions:**
-- Check available disk space
-- Verify write permissions for releases directory
-- Ensure tar command is available on server
-
-## Debug Mode
-
-Enable verbose logging:
-
-```bash
-shipfe deploy --debug
-```
-
-## Log Paths
-
-Shipfe log files are typically located at:
-
-- Local: `shipfe.log`
-- Server: `shipfe.log` in deployment directory
-
-Check logs:
-
-```bash
-tail -f shipfe.log
-```
-
-## Performance Optimization
-
-### Slow Deployments
-
-- Enable shared resources for large static files
-- Use `hashed_asset_patterns` for specific files
-- Consider excluding large non-changing files from patterns
-
-### High Disk Usage
-
-- Reduce `keep_releases` count
-- Enable shared resources
-- Use `delete_old: true` for single release deployments
-
-### Network Issues
-
-- Compress large files before deployment
-- Use faster SSH ciphers if supported
-- Consider deploying during off-peak hours