Weedbox Project Development

Source of Truth: This file is the complete reference for weedbox project creation and structure. DO NOT browse GitHub to look up source code.

This skill helps create and structure projects using the weedbox framework.

Contents

• Project Structure
• Entry Point (main.go)
• Module Loading (modules.go)
• Three-Phase Module Loading
• Configuration
• Creating a New Project
• Docker / Containerization — full template in references/docker.md
• Multi-Instance Deployment — one binary, config-driven dev/production backends
• License Selection — full texts in references/licenses.md
• Common Modules from weedbox/common-modules
• User Modules from weedbox/user-modules
• Running the Application
• Project Checklist

Project Structure

myproject/
├── LICENSE                 # Project license file
├── README.md               # Project documentation
├── main.go                 # Application entry point with CLI setup
├── modules.go              # Module loading configuration
├── config.toml             # Configuration file (NOTE: must be named config.toml)
├── docker/
│   └── Dockerfile          # Multi-stage container build (generated by wbox init)
└── pkg/                    # Modules directory
    └── mymodule/
        └── module.go       # Module implementation

wbox init generates docker/Dockerfile alongside the Go source. When hand-crafting a project without wbox, do not forget to add docker/Dockerfile — it is part of the canonical layout. See references/docker.md for the template.

Entry Point (main.go)

The main entry point uses Cobra CLI and Uber FX for dependency injection.

Important: configs.NewConfig("MYAPP") automatically reads config.toml from current directory or ./configs/ directory. The application runs using fx.New().Run().

package main

import (
    "os"

    "github.com/spf13/cobra"
    "github.com/weedbox/common-modules/configs"
    "go.uber.org/fx"
)

const (
    appName        = "myapp"
    appDescription = "My Weedbox Application"
)

var config *configs.Config

var printConfigs bool
var verbose bool

func main() {
    rootCmd := &cobra.Command{
        Use:   appName,
        Short: appDescription,
        RunE: func(cmd *cobra.Command, args []string) error {
            if err := run(); err != nil {
                return err
            }
            return nil
        },
    }

    // Initialize config - automatically reads config.toml
    config = configs.NewConfig("MYAPP")
    rootCmd.Flags().BoolVar(&printConfigs, "print_configs", false, "Print all available configs")
    rootCmd.Flags().BoolVar(&verbose, "verbose", false, "Display detailed logs")

    err := rootCmd.Execute()
    if err != nil {
        os.Exit(1)
    }
}

func initModules() ([]fx.Option, error) {
    modules := []fx.Option{}

    m, err := preloadModules()
    if err != nil {
        return modules, err
    }
    modules = append(modules, m...)

    m, err = loadModules()
    if err != nil {
        return modules, err
    }
    modules = append(modules, m...)

    m, err = afterModules()
    if err != nil {
        return modules, err
    }
    modules = append(modules, m...)

    // Disable fx verbose logging unless --verbose flag is set
    if !verbose {
        modules = append(modules, fx.NopLogger)
    }

    return modules, nil
}

func run() error {
    modules, err := initModules()
    if err != nil {
        return err
    }

    // Create and run the fx application
    app := fx.New(modules...)

    // Print configs if requested
    if printConfigs {
        config.PrintAllSettings()
    }

    // Run the application (blocks until shutdown signal)
    app.Run()

    return nil
}

Module Loading (modules.go)

Modules are loaded in three phases for proper initialization order.

package main

import (
    "github.com/weedbox/common-modules/daemon"
    "github.com/weedbox/common-modules/logger"
    "go.uber.org/fx"

    "myproject/pkg/mymodule"
)

// preloadModules - Phase 1: Configuration and logging
func preloadModules() ([]fx.Option, error) {
    modules := []fx.Option{
        fx.Supply(config),
        logger.Module(),
    }
    return modules, nil
}

// loadModules - Phase 2: Application modules
func loadModules() ([]fx.Option, error) {
    modules := []fx.Option{
        mymodule.Module("mymodule"),
    }
    return modules, nil
}

// afterModules - Phase 3: Daemon and lifecycle
func afterModules() ([]fx.Option, error) {
    modules := []fx.Option{
        // Optional: lifecycle before daemon, when modules need PostStart /
        // PreStop hooks (run after all modules start / before any stops)
        lifecycle.Module("lifecycle"),
        daemon.Module("daemon"),
    }
    return modules, nil
}

Three-Phase Module Loading

Configuration

Config File (config.toml)

Important: The config file must be named config.toml (not configs.toml). It should be placed in the current directory or ./configs/ directory. configs.NewConfig("MYAPP") automatically reads this file.

[mymodule]
timeout = "30s"
enabled = true

Environment Variables

Environment variables override config file settings. The prefix is set in configs.NewConfig("MYAPP").

# Format: {PREFIX}_{SECTION}_{KEY}
# Dots and dashes in keys are replaced with underscores
export MYAPP_MYMODULE_TIMEOUT=60s
export MYAPP_MYMODULE_ENABLED=true

Creating a New Project

Use wbox CLI tool to create a new project.

Install wbox

go install github.com/weedbox/wbox@latest

Initialize Project

mkdir myproject
cd myproject
wbox init myproject github.com/myuser/myproject

This generates the canonical project layout including main.go, modules.go, LICENSE, README.md, go.mod, go.sum, and a docker/Dockerfile multi-stage build. The generated modules.go is intentionally minimal (only logger + daemon) — wire in business modules manually.

If wbox is not on $PATH, run it without a global install via go run github.com/weedbox/wbox@latest init myproject github.com/myuser/myproject. The binary fetched by go install lands in $GOPATH/bin, which is not always on the user's shell $PATH — go run sidesteps that.

Add Modules Manually

Create modules in pkg/ directory by hand. See module-dev for detailed guidance.

Docker / Containerization

wbox init generates a multi-stage docker/Dockerfile (Go build stage + minimal Alpine runtime, non-root user, /datastore volume mountpoint). Adapt the template to your project: Go version to match go.mod, EXPOSE port to match config.toml, CGO_ENABLED when using sqlite_connector, and a config copy if the app needs config.toml at startup. Pair it with a .dockerignore to keep the build context small.

Full template, adaptation table, .dockerignore, and build/run commands: references/docker.md.

Multi-Instance Deployment

Production deployments run multiple replicas of the same binary. Design for this from day one: one binary, one module list, and configuration (not code) selects single-instance dev backends vs multi-instance production backends. Full decision table: root skill § Design for Multi-Instance Deployment by Default.

Recommended pattern: PostgreSQL everywhere, config-only switching

The lowest-friction setup uses PostgreSQL in every environment (run it via Docker locally). Dev → production is then pure configuration — modules.go never changes:

// modules.go — identical in dev and production
func loadModules() ([]fx.Option, error) {
    return []fx.Option{
        postgres_connector.Module("database"),
        scheduler.Module("scheduler"),          // mode from config: gorm (dev) / postgres (prod)
        postgres_workqueue.Module("workqueue"), // multi-process safe in every environment
        // ... business modules ...
    }, nil
}

# config.toml — development defaults (single local process)
[scheduler]
mode = "gorm"

# Production — environment variables override config.toml
export MYAPP_SCHEDULER_MODE=postgres   # claim-based multi-instance scheduling
export MYAPP_DATABASE_HOST=db.internal
export MYAPP_DATABASE_PASSWORD=secret

scheduler postgres mode shares gorm mode's tables, so the switch requires no data migration.

SQLite-based development

If local development must be dependency-free, use SQLite in dev — the swap stays confined to modules.go because application code injects interfaces (database.DatabaseConnector, workqueue.WorkQueue) only:

NATS-based stacks

Run the embedded JetStream server in development and point at an external NATS cluster in production — config only:

# config.toml — development
[nats_server]
enabled = true          # embedded NATS JetStream server (preload phase)

[nats]
host = "nats://localhost:4222"

# Production
export MYAPP_NATS_SERVER_ENABLED=false
export MYAPP_NATS_HOST=nats://nats.internal:4222
export MYAPP_SCHEDULER_MODE=nats

Multi-instance production rules

• Replicas > 1 → scheduler mode MUST be postgres or nats, never gorm (every replica would fire every job)
• Replicas > 1 → workqueue backend MUST be gorm_workqueue, postgres_workqueue, or nats_workqueue, never memory_workqueue
• The embedded nats_jetstream_server is for development and single-node use — production uses an external NATS cluster
• SQLite is a local file, single-node by nature — use postgres_connector when scaling out
• Cross-instance shared state (cache, locks, counters) goes in the database, redis_connector, or NATS — never process memory
• Custom modules must follow module-dev § Multi-Instance Safety

License Selection

When creating a new project, choose an appropriate license. The default is Apache License 2.0.

Available License Options

Create the LICENSE file from the matching template in references/licenses.md. Also add the per-file source header from the same reference.

Common Modules from weedbox/common-modules

User Modules from weedbox/user-modules

See user-modules skill for detailed documentation.

Running the Application

# Run with default config (reads config.toml automatically)
go run .

# Print all configurations
go run . --print_configs

# Verbose mode (shows fx dependency injection logs)
go run . --verbose

# Build and run
go build -o myapp .
./myapp
./myapp --print_configs
./myapp --verbose

Note: The config file path is not configurable via command-line flags. Place your config.toml in the current directory or ./configs/ directory.

Project Checklist

• Install wbox: go install github.com/weedbox/wbox@latest (or use go run github.com/weedbox/wbox@latest init ... to skip the install)
• Initialize project: wbox init <name> <module-path>
• Choose license: Apache-2.0 (default), MIT, or Proprietary
• Create LICENSE file with chosen license
• Create configuration file (config.toml, not configs.toml)
• Implement application modules in pkg/
• Design for multi-instance: pick production backends per the multi-instance table (scheduler mode postgres/nats, durable workqueue backend, external NATS) and keep dev/production switching config-driven
• Verify docker/Dockerfile was generated (if hand-crafted, copy the template from references/docker.md)
• Add a .dockerignore to keep the build context small
• Adapt the Dockerfile: Go version, EXPOSE port, CGO_ENABLED, config copy, <PREFIX>_DATABASE_PATH
• Add license headers to source files (for open source projects)

Related

• module-dev - Detailed module development guide
• user-modules - User management, auth, and RBAC modules