Skip to content

Migration & Setup Scripts

Referenced Files in This Document

Table of Contents

  1. Introduction

  2. Project Structure

  3. Core Components

  4. Architecture Overview

  5. Detailed Component Analysis

  6. Dependency Analysis

  7. Performance Considerations

  8. Troubleshooting Guide

  9. Conclusion

  10. Appendices

Introduction

This document explains Nexo’s build, packaging, deployment, and database migration workflows. It focuses on:

  • Python packaging and frontend compilation

  • Cross-platform deployment via build and release scripts

  • Alembic-based schema versioning, migrations, and rollbacks

  • Environment-specific configuration and dependency management

  • Initial installation and system initialization via setup scripts

  • Troubleshooting common build, migration, and deployment issues

  • Customization points for extending builds and deployments

Project Structure

The repository organizes build and setup tooling at the root level and within feature modules:

  • Root-level automation: build.py, build-v2.py, release.py, setup.py, alembic.ini

  • Database migrations: alembic/ (env, script template, versions)

  • Application service entrypoints and shared configuration under apps/service and apps/shared

  • Frontend assets under apps/dashboard (Vite + TypeScript)

  • Dependency manifests: requirements.txt (Python), package.json (Node/Bun)

graph TB

A["Root Build Scripts<br/>build.py, build-v2.py, release.py"] --> B["Python Packaging<br/>setup.py"]

A --> C["Frontend Build<br/>apps/dashboard (Vite)"]

A --> D["Release Artifacts<br/>dist/, wheels, bundles"]

E["Alembic Config<br/>alembic.ini"] --> F["Migration Runner<br/>alembic/env.py"]

F --> G["Versioned Migrations<br/>alembic/versions/*"]

H["Setup Script<br/>apps/setup/main.py"] --> I["Service App<br/>apps/service/app.py"]

J["Dependencies<br/>requirements.txt, package.json"] --> A

Diagram sources

Section sources

Core Components

  • Build orchestrators:

  • build.py: primary build pipeline (Python packaging, frontend compile, artifact assembly)

  • build-v2.py: alternate or experimental build flow

  • Release automation:

  • release.py: versioning, tagging, artifact publishing, changelog generation

  • Packaging:

  • setup.py: Python distribution metadata and install hooks

  • Database migrations:

  • alembic.ini: Alembic runtime config

  • alembic/env.py: environment bootstrap and connection handling

  • alembic/script.py.mako: migration generator template

  • alembic/versions/*: individual migration files

  • Setup and initialization:

  • apps/setup/main.py: interactive or scripted installer

  • apps/service/app.py: application entrypoint used during setup and runtime

  • Dependencies:

  • requirements.txt: Python dependencies

  • package.json: Node/Bun dependencies and scripts for frontend

Key responsibilities:

  • Ensure consistent builds across platforms

  • Generate reproducible artifacts

  • Manage schema evolution safely

  • Provide one-command setup for new environments

Section sources

Architecture Overview

High-level build and deployment architecture:

sequenceDiagram

participant Dev as "Developer"

participant Build as "build.py / build-v2.py"

participant Pack as "setup.py"

participant FE as "Frontend (Vite)"

participant Rel as "release.py"

participant DB as "Alembic (env.py)"

participant Store as "Artifact Store"

Dev->>Build : Run build pipeline

Build->>FE : Compile assets

Build->>Pack : Create wheel/sdist

Build-->>Dev : Local artifacts

Dev->>Rel : Trigger release

Rel->>DB : Apply latest migrations (optional)

Rel->>Store : Upload artifacts

Rel-->>Dev : Publish results

Diagram sources

Detailed Component Analysis

Build System (build.py and build-v2.py)

Responsibilities:

  • Orchestrate frontend compilation (Vite) and asset bundling

  • Prepare Python package using setup.py

  • Assemble cross-platform artifacts (e.g., dist directories, wheels)

  • Optionally run tests or linting pre/post build

  • Support environment flags to toggle features or targets

Typical workflow:

  • Validate prerequisites (Python, Node/Bun, Vite)

  • Clean previous outputs

  • Build frontend into static assets

  • Package Python app and include compiled assets

  • Produce platform-specific distributions

Customization points:

  • Add extra build steps (e.g., asset optimization, signing)

  • Integrate platform-specific hooks (Windows/macOS/Linux)

  • Toggle optional features via environment variables

Section sources

Frontend Compilation (apps/dashboard)

  • Uses Vite with TypeScript and CSS processing

  • Entrypoints and configuration reside under apps/dashboard

  • Build output is consumed by the backend or packaged into the final distribution

Integration with build:

  • The build scripts invoke the frontend build step and copy outputs into the Python package or distribution directory.

Section sources

Python Packaging (setup.py)

  • Declares package metadata, dependencies, and data files

  • Ensures compiled frontend assets are included in the distribution

  • May define console scripts or entry points for CLI usage

Best practices:

  • Pin critical dependencies where needed

  • Use conditional extras for optional features

  • Include only necessary assets to keep packages small

Section sources

Release Automation (release.py)

Responsibilities:

  • Version bumping and tag creation

  • Changelog generation from commit history

  • Artifact upload to a registry or storage

  • Optional post-release tasks (notifications, docs updates)

Workflow:

  • Validate current branch and tags

  • Update version references

  • Build and publish artifacts

  • Tag and push changes

Environment-specific behavior:

  • Dry-run mode for CI previews

  • Conditional publishing based on branch or tag pattern

Section sources

Alembic Database Migration Workflow

Components:

  • alembic.ini: runtime configuration (database URL, script locations)

  • alembic/env.py: connects to the database and runs migrations

  • alembic/script.py.mako: template for generating new migrations

  • alembic/versions/*: migration files that describe schema changes

Migration lifecycle:

  • Generate: create a new migration file describing changes

  • Review: ensure up() and down() are correct and idempotent

  • Apply: migrate up to target revision

  • Rollback: migrate down to previous revision if needed

flowchart TD

Start(["Start"]) --> Gen["Generate Migration<br/>alembic revision"]

Gen --> Edit["Edit Migration File<br/>up()/down()"]

Edit --> Test["Test Locally<br/>migrate up/down"]

Test --> Approve{"Approved?"}

Approve --> |No| Edit

Approve --> |Yes| Apply["Apply to Target DB<br/>migrate upgrade head"]

Apply --> Verify["Verify Schema"]

Verify --> End(["Done"])

Diagram sources

Section sources

Setup and Initialization (apps/setup/main.py)

Purpose:

  • Install dependencies

  • Generate configuration files for first run

  • Initialize the database (run Alembic upgrades)

  • Seed default data if required

  • Configure services or desktop integrations

Initialization sequence:

  • Detect OS and environment

  • Prompt for or read configuration values

  • Create config files in standard locations

  • Run database migrations

  • Start or register background services

Section sources

Service Entry Point (apps/service/app.py)

  • Initializes application components and routes

  • Loads configuration from generated files

  • Integrates with database via Alembic-managed schema

  • Exposes APIs and UI endpoints

Section sources

Dependency Analysis

External dependencies and their roles:

  • Python: managed via requirements.txt and installed through setup.py

  • Frontend: managed via package.json; built by Vite and integrated into the Python distribution

graph LR

RQ["requirements.txt"] --> PY["Python Runtime"]

PKG["setup.py"] --> PY

PJ["package.json"] --> FE["Frontend Assets"]

FE --> DIST["Distribution Bundle"]

PY --> DIST

Diagram sources

Section sources

Performance Considerations

  • Incremental frontend builds: leverage Vite caching to speed up development and CI

  • Parallelize independent steps: run linting and tests concurrently when safe

  • Minimize artifact size: exclude unnecessary assets from distributions

  • Cache dependencies: persist pip and Node caches in CI to reduce rebuild times

  • Database migrations: batch schema changes and avoid heavy operations during peak hours

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Build fails due to missing Node/Binaries

  • Ensure Node.js and Bun/Vite are installed and on PATH

  • Reinstall frontend dependencies before building

  • Check build logs for specific module resolution errors

  • Frontend assets not included in distribution

  • Confirm setup.py includes static assets

  • Verify build order: frontend must complete before packaging

  • Database migration errors

  • Validate database URL in alembic.ini

  • Ensure env.py loads correct engine and settings

  • For conflicts, inspect the latest migration and apply manually if needed

  • Rollback failures

  • Ensure down() is implemented correctly

  • If down() is not feasible, use targeted downgrade to a known good revision

  • Permission issues on Windows/macOS/Linux

  • Run setup with appropriate privileges

  • Avoid writing to protected directories; use user-scoped config paths

  • Environment-specific configuration problems

  • Use environment variables or separate config files per environment

  • Validate configuration at startup and fail fast with clear messages

Section sources

Conclusion

Nexo’s build and setup automation provides a cohesive path from source to production:

  • Centralized build orchestration ensures consistency

  • Alembic manages schema evolution safely

  • Release automation streamlines versioning and publishing

  • Setup scripts simplify initial installation and configuration

Adhering to the recommended workflows and customization points will help maintain reliability and extensibility across environments.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Quick Commands Reference

  • Build locally: run the primary build script

  • Alternate build: run the v2 build script

  • Package Python distribution: use setup.py commands

  • Generate migration: create a new Alembic revision

  • Apply migrations: upgrade to head or specific revision

  • Rollback: downgrade to previous revision

  • Initialize system: run the setup script

[No sources needed since this section provides general guidance]