ferrisup 0.1.0

A versatile Rust project bootstrapping tool - start anywhere, scale anywhere
Documentation
ferrisup-0.1.0 has been yanked.

FerrisUp CLI

A powerful Rust project bootstrapping tool - Start Anywhere, Scale Anywhere

Overview

FerrisUp CLI is a versatile command-line tool for creating and managing Rust projects with flexible templates. Like Create React App for React, FerrisUp makes it easy to start new Rust projects with the right structure and dependencies.

Features

  • Multiple Templates: From minimal binaries to full-stack applications
  • Transform Capability: Start with a simple project and scale as you grow
  • GenAI Integration: Ready-made AI model templates
  • Edge Computing: WebAssembly and serverless-ready templates
  • Embedded Systems: Support for RP2040, ESP32, STM32, and Arduino
  • Interactive CLI: User-friendly command interface

Installation

# Install from crates.io
cargo install ferrisup

# Or install from source
git clone https://github.com/jermsam/ferrisup.git
cd ferrisup
cargo install --path .

Quick Start

# Create a new minimal project
ferrisup new my_project

# Create a full-stack project
ferrisup new my_fullstack --template=full-stack

# Create an AI project
ferrisup new my_ai_app --template=gen-ai

# Create an edge computing project
ferrisup new my_edge_app --template=edge-app

# Create an embedded systems project
ferrisup new my_embedded --template=embedded

Available Templates

View all available templates:

ferrisup list

Current templates include:

  • minimal - Simple binary with a single main.rs file
  • library - Rust library crate with a lib.rs file
  • full-stack - Complete application with client, server, and shared libraries
  • gen-ai - AI-focused project with inference and model components
  • edge-app - WebAssembly-based application for edge computing
  • embedded - Embedded systems firmware for microcontrollers
  • serverless - Serverless functions for cloud deployment
  • iot-device - IoT device firmware with connectivity features
  • ml-pipeline - Machine learning data processing pipeline
  • data-science - Data science project with analysis tools

Usage

ferrisup [OPTIONS]

Commands

FerrisUp offers a variety of commands to help you bootstrap, transform, and manage your Rust projects:

new

Create a new Rust project with a predefined structure.

ferrisup new [PROJECT_NAME] [--template TEMPLATE_NAME] [--git] [--build] [--no-interactive]
  • PROJECT_NAME: Optional name for your project
  • --template: Specify a template (web, api, full-stack, etc.)
  • --git: Initialize a git repository
  • --build: Run cargo build after creation
  • --no-interactive: Create project without prompting, using default values

transform

Transform an existing project into a FerrisUp template structure.

ferrisup transform [--project PATH] [--template TEMPLATE_NAME]
  • --project: Path to existing project
  • --template: Template to transform to

list

List available templates.

ferrisup list

scale

Interactively scale a project with custom components.

ferrisup scale

preview

Preview a template without creating any files.

ferrisup preview [--template TEMPLATE_NAME]
  • --template: Template to preview

component

Manage project components (add/remove).

ferrisup component [--action ACTION] [--component-type TYPE] [--project PATH]
  • --action: Action to perform: add, remove, or list
  • --component-type: Component type: client, server, database, ai, edge, embedded, etc.
  • --project: Path to the project

config

Manage configurations (export/import).

ferrisup config [--export] [--import FILE] [--path PATH]
  • --export: Export current configuration to a file
  • --import: Import configuration from a file
  • --path: Path to export/import configuration

workspace

Manage a Cargo workspace structure for your Rust projects. This command helps you create and maintain modular projects with multiple crates organized in a workspace.

ferrisup workspace <SUBCOMMAND> [OPTIONS]

Subcommands:

  • init [PATH]: Initialize a new workspace with standard directory structure (bin, libs, services, apps)
  • add <CRATE> [PATH]: Add a new crate to the workspace
  • remove <CRATE> [PATH]: Remove a crate from the workspace
  • list [PATH]: List all workspace members
  • optimize [PATH]: Find common dependencies and move them to workspace-level

Examples:

# Initialize a new workspace
ferrisup workspace init my_workspace

# Add a library crate to the workspace
ferrisup workspace add libs/core my_workspace

# Add a binary crate
ferrisup workspace add bin/cli my_workspace

# Add a service
ferrisup workspace add services/api my_workspace

# List all workspace members
ferrisup workspace list my_workspace

# Remove a crate from the workspace
ferrisup workspace remove libs/core my_workspace

# Optimize workspace dependencies
ferrisup workspace optimize my_workspace

This command supports the "Start Anywhere, Scale Anywhere" philosophy by allowing you to:

  • Begin with a small modular project
  • Gradually add components as your application grows
  • Maintain clean boundaries between different parts of your system
  • Share code through internal libraries
  • Optimize dependency management across crates

Workspace Management

FerrisUp provides comprehensive workspace management capabilities through the workspace command:

Initialize a Workspace

ferrisup workspace --action init

This command will:

  • Create a Cargo workspace configuration
  • Discover existing crates or create new workspace structure
  • Set up common dependencies in the workspace

Add a Crate to Workspace

ferrisup workspace --action add

Add a new crate to your workspace:

  • Select crate type (client, server, shared, custom)
  • Specify crate name
  • Choose between binary or library crate

Remove a Crate

ferrisup workspace --action remove

Remove a crate from your workspace with the option to:

  • Just remove it from workspace members
  • Also delete the crate files

List Workspace Members

ferrisup workspace --action list

Show all workspace members and discovered crates.

Optimize Workspace

ferrisup workspace --action optimize

Optimize your workspace by:

  • Ensuring all crates are included in workspace members
  • Adding workspace.dependencies for common dependencies
  • Applying best practices for workspace structure

Development and Testing

FerrisUp includes a comprehensive test suite to ensure functionality and compatibility. You can run the tests with:

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run tests in specific file
cargo test --test file_name

The --no-interactive flag is especially useful for automated testing and CI/CD pipelines, allowing for the creation of projects without requiring user input.

Template Compatibility

FerrisUp supports both new and old template formats, ensuring backward compatibility with existing templates. The system automatically converts older templates to the newer format.

Contributing

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

  1. Fork the repository
  2. Create your feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'Add some amazing feature'
  4. Push to the branch: git push origin feature/amazing-feature
  5. Open a Pull Request

Workflow

FerrisUp follows a simple workflow:

┌─────────────────────┐
│  Command Selection  │
│  new, transform,    │
│  scale, list        │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Project Location   │
│  Current dir or     │
│  specified path     │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Template Selection │
│  Choose template or │
│  customize          │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Component Selection │
│ Client, Server,     │
│ Database, etc.      │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Technology Stack    │
│ Framework, language │
│ and tools           │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   Configuration     │
│   Git, CI/CD,       │
│   Dependencies      │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   Project Created   │
│   or Transformed    │
└─────────────────────┘

Each step is optional and can be skipped if you provide the information via command-line parameters. FerrisUp only prompts for what it needs to complete your task.

Configuration

Configure through JSON or environment variables:

{
  "project_name": "my_rust_app",
  "template": "full-stack",
  "components": {
    "client": {
      "apps": ["web", "mobile"],
      "frameworks": ["dioxus", "tauri"]
    },
    "server": {
      "services": ["api", "auth"],
      "frameworks": ["poem", "axum"]
    },
    "database": {
      "enabled": true,
      "engines": ["postgres", "redis", "neo4j", "milvus"],
      "migration_tool": "sqlx"
    },
    "libs": {
      "modules": ["core", "models", "auth"]
    },
    "binaries": {
      "apps": ["cli", "server", "worker"],
      "types": ["app", "service", "utility"]
    },
    "ai": {
      "models": ["llama", "whisper"],
      "backends": ["candle"],
      "features": ["text-generation", "speech-to-text"]
    },
    "edge": {
      "targets": ["wasm", "cloudflare-workers"],
      "features": ["serverless", "cdn-integration"]
    },
    "embedded": {
      "targets": ["rp2040", "esp32"],
      "features": ["no-std", "real-time", "low-power"]
    }
  },
  "dependencies": {
    "dioxus": { "version": "0.4", "features": ["web"] },
    "poem": { "version": "1.3" },
    "sqlx": { "version": "0.7", "features": ["postgres"] }
  },
  "templates": {
    "full-stack": ["client", "server", "database", "libs"],
    "backend-only": ["server", "database", "libs"],
    "frontend-only": ["client", "libs"],
    "api-service": ["server", "database", "libs"],
    "library": ["libs"],
    "minimal": ["binaries"],
    "hello-world": ["binaries", "libs"],
    "cli-app": ["binaries"],
    "gen-ai": ["ai", "server", "libs"],
    "edge-app": ["edge", "libs"],
    "iot-device": ["embedded", "libs"],
    "ml-pipeline": ["ai", "server", "database", "libs"],
    "serverless": ["server", "database", "libs"],
    "data-science": ["ai", "server", "database", "libs"]
  }
}

Maximum Flexibility: From Hello World to Enterprise Scale

FerrisUp is designed with maximum flexibility in mind, allowing you to:

  1. Start Small: Begin with a simple hello-world application
  2. Grow Incrementally: Add components as your needs evolve
  3. Scale Massively: Deploy to enterprise-grade infrastructure

Starting from Minimal

Use the --minimal flag to create a bare-bones Rust project:

ferrisup new my_project --minimal

This creates a simple "Hello, World!" application with a clean workspace structure that's ready to expand.

Binary Applications

FerrisUp supports standalone binary applications with the binaries component:

"binaries": {
  "apps": ["cli", "server", "worker"],
  "types": ["app", "service", "utility"]
}

Perfect for command-line tools, background workers, or microservices.

Template Selection

FerrisUp offers a variety of templates to match your project needs:

Core Templates

  • minimal - Simple binary with a single main.rs file
  • library - Rust library crate with a lib.rs file
  • full-stack - Complete application with client, server, and shared libraries

Specialized Templates

  • gen-ai - AI-focused project with inference and model components

    • LLaMA, BERT, Whisper, and Stable Diffusion integration options
    • Model serving and inference optimization

  • edge-app - WebAssembly-based application for edge computing

    • Cloudflare Workers, Deno Deploy support
    • WASM optimized components

  • embedded - Embedded systems firmware for microcontrollers

    • Support for RP2040, ESP32, STM32, Arduino
    • HAL abstraction and peripheral management

  • serverless - Serverless functions for cloud deployment

    • AWS Lambda, Azure Functions, Google Cloud Functions
    • Local development and testing support

  • iot-device - IoT device firmware with connectivity features

    • MQTT, HTTP, and Bluetooth connectivity
    • Secure boot and OTA update support

  • ml-pipeline - Machine learning data processing pipeline

    • Data ingestion, transformation, and model training
    • Result visualization and export

  • data-science - Data science project with analysis tools

    • Data loading and preprocessing
    • Analysis, visualization, and reporting

All templates can be fully customized during the interactive setup process. You're never locked into any specific technology stack or architecture.

Enterprise Scaling

When you're ready to scale, use the --scale flag to generate deployment configurations:

ferrisup new my_enterprise_app --scale

This adds:

  • Docker configuration: Optimized multi-stage build
  • Kubernetes manifests: Deployment, service, and scaling
  • CI/CD pipelines: GitHub Actions workflows
  • Cloud deployments: AWS, GCP, Azure, and Digital Ocean templates

Start Anywhere, Scale Anywhere

FerrisUp truly embodies the "start anywhere, scale anywhere" philosophy with its transformation capability. You can begin with the simplest project and evolve it as your needs grow:

Transformation

# Start with a minimal project
ferrisup new my_project

# Later transform it to a library
ferrisup transform --project=my_project --template=library

# Add AI capabilities when needed
ferrisup transform --project=my_project --template=gen-ai

# Eventually scale to a full-stack application
ferrisup transform --project=my_project --template=full-stack

# Add enterprise scaling when ready for production
ferrisup scale --project=my_project

This transformation feature intelligently:

  • Converts binaries to libraries when appropriate
  • Preserves your existing code
  • Adds only the components you need
  • Updates your workspace configuration

Project Structure

project_name/
├── Cargo.toml
├── client/
│   ├── app1/
│   ├── app2/
│   └── common/
├── server/
│   ├── service1/
│   ├── service2/
│   └── common/
├── database/
│   ├── migrations/
│   ├── schema/
│   ├── seeds/
│   └── src/
├── libs/
│   ├── core/
│   ├── models/
│   └── auth/
├── binaries/
│   ├── cli/
│   ├── server/
│   └── worker/
├── ai/
│   ├── models/
│   ├── backends/
│   └── features/
├── edge/
│   ├── targets/
│   └── features/
├── embedded/
│   ├── targets/
│   └── features/
└── deploy/
    ├── docker/
    ├── kubernetes/
    ├── github-actions/
    └── cloud-deployments/

Database Integration

FerrisUp supports a comprehensive range of database technologies:

SQL Databases

  • PostgreSQL: Traditional relational database with advanced features
  • MySQL: Popular open-source relational database
  • SQLite: Lightweight file-based SQL database

NoSQL Databases

  • Redis: In-memory data structure store, cache, and message broker

Vector Databases

  • Milvus: Open-source vector database for similarity search and AI applications
  • Qdrant: Vector database for vector similarity search

Graph Databases

  • Neo4j: Graph database with powerful query capabilities
  • DGraph: Distributed graph database with GraphQL integration
  • ArangoDB: Multi-model database for graphs, documents, and key-value pairs

Time Series Databases

  • ScyllaDB: High-performance NoSQL database compatible with Cassandra

Semantic/Knowledge Databases

  • TypeDB: Logical database for knowledge engineering

P2P/Decentralized Databases

  • Iroh: Rust-native distributed database for peer-to-peer applications
  • Hypercore: Append-only log for peer-to-peer applications

ORM/Query Builders

  • SQLx: Async SQL toolkit with compile-time checked queries
  • Diesel: Type-safe ORM with powerful query builder
  • SeaORM: Async ORM with active record pattern

Each integration includes:

  • Connection pool setup
  • Environment variable configuration
  • Error handling
  • Migration structures (where applicable)
  • Sample schemas and models

Choosing Database Engines

Configure your database engines in the config.json file:

"database": {
  "enabled": true,
  "engines": ["postgres", "redis", "neo4j", "milvus"],
  "migration_tool": "sqlx"
}

FerrisUp will automatically generate the appropriate code and connections for each selected engine.

From Zero to Production

FerrisUp allows your project to evolve naturally:

  1. Start with a minimal hello world app
  2. Add libraries for shared functionality
  3. Create service components as needed
  4. Integrate databases when persistence is required
  5. Add client interfaces when a UI is needed
  6. Deploy to production with enterprise-grade infrastructure

Your app can remain as simple as needed or grow to any scale imaginable, all without changing tools or frameworks.

Requirements

  • Bash shell
  • Rust and Cargo
  • Git (optional)
  • jq (recommended)

License

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