Publishing & installing your module¶

You build modules in your own git repository and ship them to a running Victor app through Victor Cloud. The path is short: keep your module in a git repo (your overlay), connect that repository to Victor Cloud once, deploy a branch to an instance, then install or upgrade the module from the app's Module Manager. Every push after the first deploy re-deploys automatically.

This page walks the whole loop end to end.

What a module is¶

A module is a folder in your git repository that contains a module.yaml manifest alongside its code and views (models/, views/, and so on). The manifest is what marks the folder as a module — any folder that contains a module.yaml, anywhere in the repository, is picked up and delivered as a module when you deploy.

Your repository is your overlay: it can hold a single module folder or several, side by side. Deploying the repo delivers every module folder it contains.

your-repo/
  acme_crm/
    module.yaml
    models/
      lead.py
      contact.py
    views/
      lead.xml
      inherit_contact.xml

The manifest declares the module's identity and what it loads:

name: acme_crm
label: Acme CRM
version: 0.1.0
requires: [contact]
models: [models]
data: [views/lead.xml, views/inherit_contact.xml]

Key	Meaning
`name`	Technical id of the module. Used internally and by other modules' `requires`.
`label`	Human-readable name shown in the Module Manager.
`version`	Module version. Bump it when you ship changes; it records which version each instance has installed.
`requires`	List of other module names this module depends on (installed first). Here it extends the built-in `contact` app.
`models`	List of directories holding your model source.
`data`	List of view/data XML files to load, in order.

For how to write the pieces inside a module, see Models & fields and Views.

Start from a real module

The built-in contact app and the acme_crm sample are the shape a customer repo mirrors. acme_crm extends contact — a good template for adding your own app that builds on what ships in the box.

How Victor Cloud is organized¶

Before you can deploy, it helps to know the structure the dashboard gives you:

A project is your top-level workspace in Victor Cloud.
A project is split into environments — Production and Staging.
Each environment holds one or more instances. An instance is an isolated running Victor app with its own data and its own URL.

Because each instance is separate, you can point a Staging instance at a work-in-progress branch and keep Production on your stable branch — the two never share data.

Connect your GitHub account (once)¶

The Deploy wizard reads the repositories and branches straight from your account, so you never type them by hand. Before your first deploy, connect GitHub:

Open Settings in the Victor Cloud dashboard.
Authorize the GitHub connection.

This is a one-time authorization per user. Once connected, Victor Cloud can list your repositories and branches in the Deploy wizard. You can disconnect it later from the same screen.

Note

You only do this once. After GitHub is connected, deploying any repo to any instance is just a couple of clicks.

Deploy a repository to an instance¶

Deploying is a two-step wizard on an instance's page. You must be the project owner or admin.

Open the instance you want to deploy to.
Start the Deploy wizard.
Step 1 — Repository. Pick the repository from your connected account.
Step 2 — Branch. Pick the branch to deploy.
Click Deploy.

Victor delivers that repository's module folders (every folder containing a module.yaml) to the instance.

Each instance is deployed independently against its own selected branch. A common setup:

Environment	Instance points at
Staging	your feature branch
Production	your `main` branch

Automatic re-deploys after the first push¶

After the first manual deploy, the instance watches the repository and branch you chose. From then on, every push to that branch triggers a new deploy automatically — no need to open the wizard again. Push your changes, and the instance rebuilds itself.

Follow the build¶

Every deploy is recorded as a build in the Builds timeline on the instance page. Each build shows:

Field	What it tells you
Status	`queued` → `building` → `success` or `failed`
Branch	The branch the build was made from
Commit	The short commit SHA the build was made from
Date	When the build ran

The build runs your module's tests. If a test fails, the build is marked failed — so a broken change is caught before it reaches a running app. A green success build means your modules were delivered to the instance.

A red build protects the running app

A failed build means your tests didn't pass, so the change was not applied to the instance — the app keeps running the last good build. Fix the problem and push again; the next green build supersedes it.

Install & manage the module in the app¶

Delivering a module to an instance makes it available; you turn it on from inside the app. Open the running instance and go to the top-level Modules section — this is the Module Manager.

The Module Manager lists the modules you can manage on this instance — built-in system modules are hidden — with each one's state (installed / uninstalled) and its version, and offers state-aware actions:

Action	Shown when	What it does
Install	The module is uninstalled	Sets up the module on this instance.
Upgrade	The module is installed	Re-applies your latest module code (see below).
Uninstall	The module is installed and can be removed	Removes the module and its data (see below).

Install¶

Use Install to turn on a module the first time it is delivered to an instance. Its dependencies (everything in requires) are installed first.

Upgrade¶

Upgrade is available for any installed module. Use it after you push a change to re-apply your module's latest code to the instance — bumping version first is good practice so you can see which version is installed, but the action is always there. Upgrade is non-destructive:

Your existing records are kept.
New fields and views are added.
Seed / default data is refreshed without overwriting edits you made.
The installed version is bumped to match.

So the everyday loop after your first release is: edit code → bump version → push → build goes green → click Upgrade.

Uninstall¶

Uninstall removes the module and its data. Because other modules may build on it, uninstall cascades: any module that depends on the one you remove is uninstalled too. You're asked to confirm before it runs.

Uninstall removes data

Uninstalling a module removes the module's data and cascades to every module that depends on it. Upgrade is the safe, non-destructive path for shipping changes — reach for Uninstall only when you genuinely want the module and its data gone.

Your modules survive restarts and upgrades¶

Modules you've deployed persist across instance restarts and platform upgrades — the instance keeps its data. You deploy and install once; routine maintenance doesn't wipe your work.

The loop, end to end¶

Put your module folder (with its module.yaml) in a git repository.
Connect GitHub to Victor Cloud once, in Settings.
On an instance, run the two-step Deploy wizard: repository, then branch.
Watch the build turn green in the Builds timeline (it runs your tests).
In the app's Module Manager, click Install.
Later: edit → bump version → push. The instance re-deploys automatically; click Upgrade.

From here, dig into what goes inside a module: Models & fields and Views.