# Design: Storing OCI Artifacts
**Author**: @jonathanj
<!-- Status of the document - draft, in-review, etc. - is conveyed via HackMD labels -->

## Description (what)

Create an artifact storing scheme that decouples release creation and deployment.

## Motivation (why, optional)

The short-term strategy of storing artifacts on the controller (via deployment) complicates the effort to decouple release and deployment.

## Goals

* P1 - Decouple module artefact publishing and release
* P2 - Gain the ability to bundle deployment content into the artefact

### Non-Goals (optional)

* Porting historical images to OCI registry

## Design (how)

Currently, artefact publishing and deployment happen as part of one operation `ftl deploy`. When new module artefacts are discovered during deploy they get uploaded to the ftl controller and their image is persisted in the `artefacts` table. This artefact persistence strategy will be replaced by OCI registries.

### OCI Registries
OCI registries store container images known as artefacts. Interactions with OCI registries happen through repositories. This is a top-level container of artefact content whose access is gated by authorization. Today the `artefacts` table effectively serves as a repository. Mapping the `ftl-project` to OCI repository seems ideal given project module isolation seems desired and it provides a means for OCI repository credential management at the `ftl-project` level.

### OCI Artifacts
The OCI repository cab be used as a drop-in replacement for the `artefacts` table. `artefact` table writes (*of module images*) can be replaced with OCI repository artefact pushes. The artefacts fetches that occur during the deployment step would be replaced with artefact `pulls`. While, in the drop-in case, such artefacts will consist of a single file; OCI artefacts are packages that may contain many. The artefact also carries a type, much like a MIME type, which is used the categorize the artefact. This metadata would be use useful should we wish to later change the package structure to make better use of OCI package capabilities (e.g. introducing new data deployment artefact types).

### Open Considerations

**Ironing out credential management**

Access to OCI repositories, via the ORAS client library, is authenticated; can existing credential management schemes be used here?

### Required changes (how)

Using the OCI registry as a `artefact` table drop-in replacement breaks down into these refactor tasks:
* Refactor artefact upload / download behavior from `internal/buildengine/deploy.go` into `artefacts.go`
* Introduce `upload` and `download` operations
* These are the integration points for the OCI registry and leaves some room to support multiple implementation strategies to support migration efforts
* Update schema to allow deployment-to-artefact linking for OCI based artefacts
* Identify artefact naming scheme and custom media type
* e.g. name: `<module_name>:<version>`
* e.g. media-type: `application/ftl.module`
* **TODO**: break-down `ftl-project` OCI repository credential management scheme.

**TODO**: more consideration for the migration path/hazards from `artefacts` table to OCI registry.

## Rejected Alternatives (optional)

<!-- Other ideas that were considered but rejected, including reasoning. -->