FDE

A manual deployment tool for environments where CI/CD is unavailable.

Lightweight, single-binary, and air-gap ready.

🎯 When to use FDE?

FDE is not a replacement for modern CI/CD pipelines (GitHub Actions, GitLab CI). Instead, it is designed for specific scenarios where those tools cannot be used:

🚫 Air-Gapped Networks: The deployment target has no internet connection.
🛡️ Bastion Hosts: You must deploy through a jump server (bastion).
🔌 Direct Connection: You need a simple way to push files from a local machine to a remote server.
⚡ Rapid Iteration: Instant deployment without waiting for complex CI queues.

🚀 Quick Start

Follow these steps to get your deployment system up and running in minutes.

1. Installation

Install both the server and client binaries on your respective machines.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/yuchenii/fde/main/scripts/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/yuchenii/fde/main/scripts/install.ps1 | iex

2. Configure Server

On your server, create a server.yaml file:

Generate a random token first:

openssl rand -hex 32

port: 3000 # Port to listen on
limits:
  chunkStorageMB: 10240 # Total chunk storage (10 GiB)
  chunkFileMB: 10240 # Per-file chunk upload limit (10 GiB)
  zipExtractMB: 2048 # Maximum uncompressed ZIP size (2 GiB)
environments:
  prod:
    token: "<64-hex-token>" # Paste the generated token here
    uploadPath: "/var/www/html" # Where files will be extracted
    deployCommand: "nginx -s reload" # Command to run after extraction

3. Start Server

Start the FDE server using the config file you just created:

# Start in foreground
fde-server start -c server.yaml

# Or run in background (Daemon mode)
fde-server start -d -c server.yaml

Resource limits are configured in server.yaml. Capacity values use MB; chunkFileMB defaults to chunkStorageMB and cannot exceed it.

4. Deploy

On your local machine (where your code is), create a deploy.yaml file:

# Optional: Outer-level defaults
token: "<64-hex-token>" # Global token fallback. Same token as the server
serverUrl: "https://deploy.example.com" # Global server URL fallback. Use HTTPS outside a trusted private network

environments:
  prod:
    # token and serverUrl inherit from outer-level if not specified
    buildCommand: "npm run build" # Command to build your project
    localPath: "./dist" # Local folder to upload

Then run the deploy command:

fde-client deploy -e prod

Plain HTTP is supported only for trusted private networks. For public or otherwise untrusted networks, expose FDE through a TLS reverse proxy. FDE uses X-Real-IP for authentication throttling when present, so the proxy must overwrite it with the direct client address and clients must not be able to bypass the proxy.

📖 Detailed Usage

Commands

Server Commands

# Start server
fde-server start -c server.yaml

# Manage daemon (Unix-like systems only)
fde-server start -d -c server.yaml
./scripts/stop-server.sh

# Update server
fde-server upgrade

# Uninstall server
fde-server uninstall

# Check version
fde-server --version

# Show help
fde-server --help

Client Commands

# Deploy to specific environment
fde-client deploy -e prod

# Skip build step (skip build command execution)
fde-client deploy -e prod --skip-build

# Trigger deployment command only (no build/upload)
fde-client deploy -e prod --trigger-only

# Check server connectivity
fde-client ping -e prod
fde-client ping -s http://localhost:3000

# Check server health
fde-client health -e prod
fde-client health -s http://localhost:3000

# Update client
fde-client upgrade

# Uninstall client
fde-client uninstall

# Show version
fde-client --version

# Show help
fde-client --help

Configuration

Server Configuration (`server.yaml`)

Field	Type	Required	Default	Description
`port`	`number`	Yes	-	Port for the server to listen on.
`token`	`string`	No	-	Global security token. Used if an environment doesn't specify one.
`environments`	`object`	Yes	-	Dictionary of environment configurations (e.g., `prod`, `test`).
`log.path`	`string`	No	`./fde-server.log`	Path to the log file. Resolved relative to config file.
`log.maxSize`	`number`	No	`10`	Maximum log file size in MB before rotation.
`log.maxBackups`	`number`	No	`5`	Number of rotated log files to keep.
`limits.chunkStorageMB`	`number`	No	`10240`	Total reserved chunk storage in MB.
`limits.chunkFileMB`	`number`	No	Same as chunk storage	Per-file chunk upload limit in MB.
`limits.zipExtractMB`	`number`	No	`2048`	Maximum uncompressed ZIP size in MB.

Environment Object (environments.<name>):

Field	Type	Required	Default	Description
`token`	`string`	No	Global `token`	Environment-specific token. Overrides global token.
`uploadPath`	`string`	Yes	-	Absolute path or path relative to config file where files will be extracted.
`deployCommand`	`string`	Yes	-	Command executed after extraction.
`env`	`object`	No	-	Environment variable config for deploy commands. See docs.

Client Configuration (`deploy.yaml`)

Field	Type	Required	Default	Description
`token`	`string`	No	-	Global security token fallback.
`serverUrl`	`string`	No	-	Global server URL fallback. Used if env doesn't specify one.
`environments`	`object`	Yes	-	Dictionary of environment configurations.

Environment Object (environments.<name>):

Field	Type	Required	Default	Description
`serverUrl`	`string`	No	Global `serverUrl`	Full URL of the FDE server. Falls back to outer-level `serverUrl`.
`token`	`string`	No	Global `token`	Auth token matching the server's environment token.
`localPath`	`string`	Yes	-	Local directory or file to deploy. Resolved relative to config file.
`buildCommand`	`string`	No	-	Command to run locally before upload (e.g., `npm run build`).
`exclude`	`string[]`	No	-	List of glob patterns to exclude from upload (e.g., `node_modules`, `.git`).
`env`	`object`	No	-	Environment variable config for build commands. See docs.

🐳 Docker Support

If you prefer using Docker for the server:

docker run -d \
  --name fde-server \
  -p 3000:3000 \
  -v "./server.yaml:/app/server.yaml:ro" \
  -v "${HOME}/.ssh/fde_docker:/root/.ssh/id_rsa:ro" \
  -v "./deploy-packages:/app/deploy-packages" \
  -v "./logs:/app/logs" \
  -e SSH_USER=fde-deploy \
  -e SSH_HOST=host.docker.internal \
  -e SSH_PORT=22 \
  -e HOST_CONFIG_DIR="$(pwd)" \
  -e TZ=Asia/Shanghai \
  --add-host host.docker.internal:host-gateway \
  yuchenii/fde-server:latest

This example publishes FDE directly to a trusted private network. When a TLS reverse proxy runs on the same host, use -p 127.0.0.1:3000:3000 instead.

See Docker Deployment Guide for advanced configurations.

📚 Documentation

🏗️ Architecture

graph LR
    subgraph Client["🖥️ fde-client"]
        DC[deploy.yaml] --> CL[Load Config]
        CL --> F["-e frontend"]
        CL --> B["-e backend"]
        F --> BF[Build Command]
        B --> BB[Build Command]
        BF --> ZF["Zip + Checksum"]
        BB --> ZB["Zip + Checksum"]
    end

    ZF --> |Upload| Server
    ZB --> |Upload| Server

    subgraph Server["🖧 fde-server"]
        SC[server.yaml] --> SL[Load Config]
        SL --> FE[frontend]
        SL --> BE[backend]
        FE --> VT1["Verify Token + Checksum"]
        BE --> VT2["Verify Token + Checksum"]
        VT1 --> EX1["Extract → ./dist/web"]
        VT2 --> EX2["Extract → ./dist/api"]
        EX1 --> FD[Deploy Command]
        EX2 --> BD[Deploy Command]
    end

🔧 Development

📋 Prerequisites

Bun >= 1.0

🛠️ Setup

# Install dependencies
bun install

# Start server with hot reload
bun run dev:server

# Start client with hot reload
bun run dev:client

# Run tests
bun test

# Run tests in watch mode
bun run test:watch

🔨 Build

# Build all platforms
bun run build:all

# Build specific platform
bun run build:mac
bun run build:linux
bun run build:windows

# Build specific architecture
bun run build:mac:arm64
bun run build:linux:x64

🧪 Testing

# Run all tests
bun test

# Run with coverage
bun run test:coverage

# Watch mode
bun run test:watch

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with Bun
Progress bars powered by cli-progress
Archive handling with archiver

Name		Name	Last commit message	Last commit date
.agents		.agents
.claude		.claude
.github		.github
docs		docs
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.release-it.json		.release-it.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY-AUDIT.md		SECURITY-AUDIT.md
SECURITY.md		SECURITY.md
bun.lock		bun.lock
commitlint.config.cjs		commitlint.config.cjs
deploy.yaml		deploy.yaml
docker-compose.yml		docker-compose.yml
mise.toml		mise.toml
package.json		package.json
server.yaml		server.yaml
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

FDE

🎯 When to use FDE?

🚀 Quick Start

1. Installation

2. Configure Server

3. Start Server

4. Deploy

📖 Detailed Usage

Commands

Server Commands

Client Commands

Configuration

Server Configuration (`server.yaml`)

Client Configuration (`deploy.yaml`)

🐳 Docker Support

📚 Documentation

🏗️ Architecture

🔧 Development

📋 Prerequisites

🛠️ Setup

🔨 Build

🧪 Testing

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

FDE

🎯 When to use FDE?

🚀 Quick Start

1. Installation

2. Configure Server

3. Start Server

4. Deploy

📖 Detailed Usage

Commands

Server Commands

Client Commands

Configuration

Server Configuration (server.yaml)

Client Configuration (deploy.yaml)

🐳 Docker Support

📚 Documentation

🏗️ Architecture

🔧 Development

📋 Prerequisites

🛠️ Setup

🔨 Build

🧪 Testing

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Server Configuration (`server.yaml`)

Client Configuration (`deploy.yaml`)