femic.instance_bootstrap Module

The femic.instance_bootstrap module owns FEMIC’s filesystem-first deployment-instance scaffold. It creates the canonical instance directory layout, writes packaged template files, and optionally downloads the standard BC-wide VRI datasets that many new deployment instances start from.

If you are debugging why femic instance init created or skipped certain files, where the template payload actually comes from, or how FEMIC expects a new instance workspace to be laid out on disk, this is the first module to read. In practice it owns:

• the canonical instance directory skeleton

• packaged template-file extraction from femic.resources.instance

• optional BC VRI download/extract behavior

• the typed result payload returned to the CLI after bootstrap

Start Here If…

Use this page first if you are trying to:

• understand what femic instance init actually writes into a new instance

• inspect which template files are packaged with FEMIC and where they land

• debug overwrite-versus-skip behavior during instance bootstrap

• trace the optional BC VRI download/extract path

Typical maintenance path:

1. Start with bootstrap_instance_workspace() for the overall workflow.

2. Read INSTANCE_DIRS and INSTANCE_TEMPLATE_FILES when the question is about the expected on-disk instance layout.

3. Inspect BC_VRI_DOWNLOADS if the issue is about dataset URLs or extract locations.

Typical Usage

The common operator-facing call is:

femic instance init --instance-root instances/reference --no-download-bc-vri

For packaged-install users who want FEMIC to place a new workspace under the configured visible user root, the CLI also supports:

femic instance init --instance-name my_new_case

That resolves the target path through ~/.femic/user.yaml (or the Windows equivalent) using paths.user_instance_root rather than requiring the user to type an absolute path each time.

The matching Python entrypoint is:

from pathlib import Path
from femic.instance_bootstrap import bootstrap_instance_workspace

result = bootstrap_instance_workspace(
    instance_root=Path("instances/reference"),
    overwrite=False,
    include_bc_vri_download=False,
)

How This Fits Into The Pipeline

This module sits at the very start of a deployment-instance lifecycle:

1. a user or maintainer runs femic instance init

2. this module creates the canonical instance workspace skeleton

3. downstream commands such as prep validate-case, run, and instance rebuild rely on that layout being present

That means this module owns the initial filesystem contract for instances, not the later runtime semantics. Once the instance exists, path resolution and workflow behavior move into femic.instance_context, femic.pipeline.io, and the guide/runbook layers.

For packaged installs, it therefore sits immediately beside the newer femic.user_config contract: user config chooses the visible root, and this module writes the actual workspace at that resolved location.

Key Entry Surfaces

The highest-value entrypoints in this module are:

• bootstrap_instance_workspace() Create the instance workspace, write templates, and optionally fetch BC VRI archives.

• DatasetDownloadSpec Typed download rule for one optional bootstrap dataset.

• InstanceInitResult Result payload summarizing which dirs/files were created, skipped, or downloaded.

Filesystem Contracts

The most important runtime contracts in this module are:

• instance bootstraps create the canonical directories in INSTANCE_DIRS

• template files are copied from packaged resources named in INSTANCE_TEMPLATE_FILES

• existing files are skipped unless overwrite=True

• optional BC VRI downloads are written under data/downloads and extracted into data/bc/vri/2024

• the CLI can summarize created/skipped/downloaded artifacts because this module returns a structured InstanceInitResult

These rules matter because later deployment-instance docs and validation logic assume the bootstrap shape produced here.

Failure Seams To Watch

The common failure boundaries in this module are:

• stale packaged templates if docs or runtime assumptions drift from the packaged instance resources, new instances will start from the wrong contract

• overwrite confusion existing files are intentionally skipped by default, which can surprise users expecting a refresh in place

• dataset download/extract failures URL, network, or zip-extract issues can leave the optional BC VRI path only partially initialized

Cross-References

Guides and references that pair especially closely with this module:

• Deployment Instance Setup

• Case Onboarding Template

• Developer Environment Bootstrap (Fresh Clone)

• CLI Reference

Related API pages:

• femic.instance_context Module

• femic.pipeline.io Module

Bootstrap helpers for creating FEMIC deployment-instance workspaces.

class femic.instance_bootstrap.DatasetDownloadSpec(name, url, archive_relpath, extract_relpath)

Bases: object

Dataset URL and local placement rules for instance bootstrap.

Parameters:

• name (str)

• url (str)

• archive_relpath (Path)

• extract_relpath (Path)

archive_relpath: Path

extract_relpath: Path

name: str

url: str

class femic.instance_bootstrap.InstanceInitResult(instance_root, created_dirs, written_files, skipped_files, downloaded_archives, extracted_dirs)

Bases: object

Result payload for deployment-instance workspace initialization.

Parameters:

• instance_root (Path)

• created_dirs (tuple[Path, ...])

• written_files (tuple[Path, ...])

• skipped_files (tuple[Path, ...])

• downloaded_archives (tuple[Path, ...])

• extracted_dirs (tuple[Path, ...])

created_dirs: tuple[Path, ...]

downloaded_archives: tuple[Path, ...]

extracted_dirs: tuple[Path, ...]

instance_root: Path

skipped_files: tuple[Path, ...]

written_files: tuple[Path, ...]

femic.instance_bootstrap.bootstrap_instance_workspace(*, instance_root, overwrite=False, include_bc_vri_download=False, message_fn=<built-in function print>, download_url_fn=<function _download_url_to_path>)

Create a filesystem-first FEMIC deployment-instance workspace.

Parameters:

• instance_root (Path)

• overwrite (bool)

• include_bc_vri_download (bool)

• message_fn (Callable[[str], None])

• download_url_fn (Callable[[str, Path], None])

Return type:

InstanceInitResult