Skip to main content

Installation

This page covers the minimum environment and project setup required to boot a VEF application.

Requirements​

The current framework version requires:

  • Go 1.26.4

The framework builds with CGO_ENABLED=0: the built-in expression engine uses the pure-Go expr-lang library, and every built-in database driver is pure Go as well. Enable CGO only when you add a native dependency of your own.

Runtime prerequisites​

If you use the default vef.Run(...) boot path, the current framework runtime always boots the database module.

That means the true minimum startup prerequisite is:

  • a reachable database
  • a valid application.toml

The default boot graph also includes the Redis module, but Redis only becomes a practical prerequisite when your application or an enabled feature actually consumes *redis.Client or another Redis-backed capability.

For the smallest local setup, use SQLite.

Add the framework​

Install the package in your Go module:

go get github.com/coldsmirk/vef-framework-go

If you are starting from an empty directory:

go mod init example.com/my-app
go get github.com/coldsmirk/vef-framework-go

Pick a database early​

VEF boots its database module during startup, so your application configuration needs a valid data source from the start. The framework supports:

  • PostgreSQL
  • MySQL
  • SQLite
  • SQL Server
  • Oracle

For local exploration and small demos, SQLite is the simplest choice because it avoids external infrastructure.

Add Redis only when needed​

If you later enable Redis-backed features, the default client settings are:

  • host: 127.0.0.1
  • port: 6379
  • network: tcp

One easy local option is:

docker run --name vef-redis -p 6379:6379 -d redis:7-alpine

Create the config file​

By default VEF looks for application.toml in:

  • ./configs
  • $VEF_CONFIG_PATH
  • .
  • ../configs

The most common layout is:

my-app/
├── configs/
│   └── application.toml
└── main.go

Minimal configuration​

This is the smallest configuration that boots — SQLite, the default in-memory storage provider, and a transactional route for vef.storage.* events (the outbox transport in this example):

[vef.app]
name = "my-app"
port = 8080

[vef.data_sources.primary]
type = "sqlite"

[vef.event.transports.outbox]
enabled = true

[[vef.event.routing]]
pattern    = "vef.storage.*"
transports = ["outbox", "memory"]

The primary data source is mandatory. It powers the framework-wide orm.DB injection; additional named data sources live under the same vef.data_sources map.

The two event blocks are not optional decoration: the storage module publishes its domain events transactionally and fails startup when no transactional route serves vef.storage.* (the default memory transport is not transactional). The route lists "memory" — the outbox's default sink (vef.event.transports.outbox.sink) — alongside "outbox" so in-process subscribers can attach to it; an outbox-only route publishes but rejects every subscription. Setting vef.event.default_transport = "outbox" is the routing-rule-free alternative. See Quick Start for the walkthrough of this exact failure.

If you omit vef.storage.provider, the framework falls back to memory storage. Add vef.redis only when the application really uses Redis-backed features.

What happens during startup​

When you call vef.Run(...), the framework initializes configuration, the data source registry and primary orm.DB, middleware, API routing, security, events (plus the tx_memory / outbox / redis-stream / inbox transport submodules), the expression engine, the JS engine, CQRS, cron, Redis, distributed locks, mold, storage, sequence, schema, monitoring, MCP, server push, and finally the HTTP application.

That is why installation in VEF is not just “import the package”. A valid config file is part of installation.

Optional environment variables​

The framework reads exactly three environment variables; all are useful during setup:

  • VEF_CONFIG_PATH: add an extra config search directory
  • VEF_LOG_LEVEL: adjust log verbosity
  • VEF_I18N_LANGUAGE: switch the framework language, defaulting to Simplified Chinese

Next step​

Continue to Quick Start to build a minimal resource and confirm the app is serving requests.