wip: more docs

docs/mkdocs.yml

@@ -7,12 +7,20 @@ docs_dir: src
 
 nav:
   - Overview: index.md
+  - News: blog/index.md
   - Installation: installation.md
   - Tutorials:
     - Getting Started: tutorials/getting_started.md
   - Concepts:
+    - Projects: concepts/projects.md
     - CI: concepts/ci.md
   - Reference:
+    - Blueprints: reference/blueprint.md
+    - Deployments: reference/deployments.md
+    - Releases:
+      - Overview: reference/releases/index.md
+      - Docker: reference/releases/docker.md
+      - GitHub: reference/releases/github.md
     - Targets: reference/targets.md
 
 theme:
@@ -45,4 +53,10 @@ markdown_extensions:
   - admonition
   - pymdownx.details
   - pymdownx.snippets
-  - pymdownx.superfences
+  - pymdownx.superfences
+
+plugins:
+  - blog:
+      archive: false
+      categories: false
+  - tags

docs/src/blog/.authors.yml

@@ -0,0 +1,5 @@
+authors:
+  jmgilman:
+    name: Joshua Gilman
+    description: Maintainer
+    avatar: https://avatars.githubusercontent.com/u/2308444?v=4

docs/src/blog/index.md

@@ -0,0 +1,2 @@
+# News
+

docs/src/blog/posts/001-whats-new-in-forge.md

@@ -0,0 +1,147 @@
+---
+draft: false
+date: 2024-10-25
+authors:
+  - jmgilman
+---
+
+# What's New in Forge - 10-25-2024
+
+Check out what's new in Forge this week.
+
+<!-- more -->
+
+## Releases
+
+The `publish` and `release` targets are no more!
+They have been replaced with an entirely new system that will enable adding more release automation going forward.
+Individual releases are now defined in a project's blueprint and Forge will automatically discover and execute them in the CI
+pipeline.
+Each release is run in parallel to maximize speed.
+
+The old targets will no longer automatically run in the CI.
+You will need to configure new releases in your project's blueprint file to continue publishing/releasing.
+The `publish` target has been replaced with the `docker` release type.
+The `release` target has been replaced with the `github` release type.
+
+For example, you can continue to use the `publish` target in your `Earthfile` by configuring a `docker` release type:
+
+```cue
+project: {
+    name: "myproject"
+    release: {
+		docker: {
+			on: {
+				merge: {}
+				tag: {}
+			}
+			config: {
+				tag: _ @forge(name="GIT_COMMIT_HASH")
+			}
+            target: "publish"
+		}
+	}
+}
+```
+
+The above configuration will create a new docker release whenever a merge to the default branch occurs or when a new git tag is
+created.
+The published image will have its tag (`config.tag` above) automatically filled in with the git commit hash.
+Finally, Forge will call the `publish` target in your `Earthfile` to generate the container image.
+
+To learn more about releases, please refer to the [reference documentation](../../reference/releases/index.md).
+
+## Deployment Templates
+
+A new command has been introduced to the CLI: `forge deploy template`.
+This command can be used to generate the raw Kubernetes manifests (in YAML) that will be applied to the target Kubernetes cluster
+during automatic deployments.
+This is useful when troubleshooting why a deplyoment may be failing or acting in an unexpected way.
+All generated manifests will be printed to `stdout` and can be redirected to a local file for easier viewing.
+
+The below example shows what it looks like to generate the raw manifests for the Foundry API server:
+
+```text
+$ forge deploy template foundry/api
+---
+# Instance: foundry-api
+---
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app.kubernetes.io/managed-by: timoni
+    app.kubernetes.io/name: foundry-api
+    app.kubernetes.io/version: 0.1.0
+  name: foundry-api
+  namespace: default
+spec:
+  ports:
+  - name: http
+    port: 80
+    protocol: TCP
+    targetPort: http
+  selector:
+    app.kubernetes.io/name: foundry-api
+  type: ClusterIP
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app.kubernetes.io/managed-by: timoni
+    app.kubernetes.io/name: foundry-api
+    app.kubernetes.io/version: 0.1.0
+  name: foundry-api
+  namespace: default
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: foundry-api
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: foundry-api
+    spec:
+      containers:
+      - image: 332405224602.dkr.ecr.eu-central-1.amazonaws.com/foundry-api:763fe7fd2bfdd39d630df9b5c5aa7e6588fc6eea
+        imagePullPolicy: IfNotPresent
+        livenessProbe:
+          httpGet:
+            path: /
+            port: http
+          initialDelaySeconds: 5
+          periodSeconds: 5
+        name: foundry-api
+        ports:
+        - containerPort: 8080
+          name: http
+          protocol: TCP
+        readinessProbe:
+          httpGet:
+            path: /
+            port: http
+          initialDelaySeconds: 5
+          periodSeconds: 5
+```
+
+For more information, please refer to the [deployments documentation](../../reference/deployments.md#templating).
+
+## What's Next
+
+Work is currenetly being done to improve automatic deployments for projects.
+Currently, Forge assumes a GitOps repository exists and will automatically generate and commit updated deployments to the configured
+repository.
+This makes setup complicated and introduces a mostly unecessary step in the deployment process.
+
+Instead, we are investigating having a GitOps operator (currently only Argo CD) point directly at a project's repository.
+Since a blueprint file is self-contained, it's possible to generate Kubernetes manifests using only the information inside of it.
+The first steps towards experimenting with this new solution was to create a
+[custom management plugin](https://github.com/input-output-hk/catalyst-forge/tree/master/tools/argocd) capable of ingesting a
+project and spitting out raw Kubernetes manifests.
+With this in place, it should be possible to point Argo CD directly at a project folder and have it generate the necessary manifests
+for deploying the project.
+As this process matures, more documentation will be released with the updated deployment process.
+
+That's it for this week, thanks for tuning in!

docs/src/concepts/projects.md

@@ -26,7 +26,7 @@ If a library is used by more than one project, or is consumed externally, it's r
 ## Project Components
 
 Forge discovers projects within a repository using a specific set of rules.
-Namely, a valid project is any folder within the repository that contains a [blueprint](./blueprints.md) (`blueprint.cue`).
+Namely, a valid project is any folder within the repository that contains a blueprint (`blueprint.cue`).
 This is the _only_ requirement for forge to classify that directory as a project.
 While a project may consist of one or more _other_ files or directories, the blueprint should always exist at the root of the
 project folder.

docs/src/index.md

@@ -16,4 +16,5 @@ It is especially inspired by the principles and philosophies of
 
 ## Getting Started
 
-If you're new to Catalyst Forge, the quickest way to get familiar with what it offers is through the getting started tutorial.
+If you're new to Catalyst Forge, the quickest way to get familiar with it is through the
+[getting started tutorial](./tutorials/getting_started.md).

docs/src/reference/blueprint.md

@@ -82,14 +82,6 @@ In the above example, the `version` field will set to the version suffix of the
 `project/v1.0.0`).
 If no tag is detected, the value will default to `dev`.
 
-
-When a project is loaded, the Forge runtime will automatically load and parse the associated blueprint file using CUE.
-For more information on CUE, please refer to the [CUE documentation](https://cuelang.org/docs/).
-
-A blueprint contains configuration for a [project](./projects.md).
-Every valid project _must_ have one single accompanying blueprint file.
-By convention, the blueprint file is named `blueprint.cue`.
-
 ### Schema
 
 The schema for blueprint files is defined in both Go and CUE.

docs/src/reference/deployments.md

@@ -0,0 +1,112 @@
+# Deployments
+
+Every project can be configured to be automatically deployed to Catalyst's development cluster.
+This allows previewing the behavior of a project after merging changes.
+
+## Background
+
+Deployments are opinionated in that they are configured to work with a certain tech stack.
+Specifically, application deployments are written using [Timoni](https://timoni.sh/), which uses CUE as the configuration language.
+Projects will generate a [bundle file](https://timoni.sh/concepts/#bundle) from the blueprint that deploys one or more
+[modules](https://timoni.sh/concepts/#module).
+This bundle file is written to the configured GitOps repository where it's expected that
+[Argo CD](https://argo-cd.readthedocs.io/en/stable/) will be responsible for reconciling it to a Kubernetes cluster.
+
+## How it Works
+
+When the CI pipeline runs, Forge will automatically scan and identify all projects that contain a `deployment` configuration block.
+At the end of the pipeline, after all releases have been executed, all projects with deployments will be deployed.
+Forge will use the `deployment` block to generate a Timoni bundle file.
+The GitOps repository (configured in `global.deployment`) is then cloned locally and the bundle file is placed in specific location
+within the repository.
+The changes are then committed and pushed back to the repository.
+This will trigger the GitOps operator (Argo CD) to consume the bundle file, generating and applying Kubernetes resources to the
+configured cluster.
+
+## Configuration
+
+The deployment behavior can be specified using the `deployment` block in the project configuration.
+For example:
+
+```cue
+project: {
+    deployment: {
+		environment: "dev"
+		modules: main: {
+			container: "foundry-api-deployment"
+			version:   "0.1.0"
+			values: {
+				environment: name: "dev"
+				server: image: {
+					tag: _ @forge(name="GIT_COMMIT_HASH")
+				}
+			}
+		}
+	}
+}
+```
+
+The following section will break down this example configuration.
+
+### Environment
+
+The `environment` field specifies which environment to deploy the project to.
+In the current version of Forge, `dev` is the only allowed value in this field (and is also the default value).
+
+### Modules
+
+Deployments can consist of one or more modules, of which one module is designated as the _main_ module.
+All modules share the same configuration fields:
+
+| Name        | Description                                         | Type   | Required | Default                     |
+| ----------- | --------------------------------------------------- | ------ | -------- | --------------------------- |
+| `container` | The name of the container holding the Timoni module | string | no       | `[project_name]-deployment` |
+| `namespace` | The kubernetes namespace to deploy to               | string | no       | `default`                   |
+| `values`    | The configuration values to pass to the module      | Object | no       | `{}`                        |
+| `version`   | The version of the container to use                 | string | yes      | N/A                         |
+
+#### Main Module
+
+The _main_ module is the Timoni module that is responsible for deploying the primary service managed by the project.
+For example, an API server's main module would configure all of the necessary Kubernetes resources required for running the server
+(like a deployment and service).
+
+#### Support Modules
+
+Support modules are modules that provide supplementary resources that the project may require.
+For example, a project may need access to a database.
+A support module can be configured to point to a Timoni module that will ensure a database is setup for the project to use.
+
+In the current version of Forge, this field is not used, as no support modules exist at the time of this writing.
+
+### Values
+
+Most Timoni modules require values to be passed in order to configure how the module goes about deploying the project.
+For example, most modules need to know the tag of the container image that should be deployed.
+In the previous example, this was set to `@forge(name="GIT_COMMIT_HASH")` which means the tag will always be set to the current
+git commit hash.
+This is the standard approach as most projects are configured with a [docker release](./releases/docker.md) that is set to
+publish images using the git commit hash.
+
+There is no enforced schema for the `values` field as it depends on the module being consumed.
+Refer to the documentation for a specific module to determine what fields are available for configuration.
+
+## Templating
+
+!!! note
+    Most modules are published to a private AWS ECR instance.
+    Because of this, you must be authenticated with AWS before trying to generate a deployment template.
+    This necessarily means external contributors will not be able to use this feature.
+
+When the deployment step in the CI activates, Forge automatically compiles the raw Kubernetes manifests from the Timoni bundle and
+passes it to Argo CD for reconciliation.
+It's possible to generate these manifests yourself using the `forge deploy template` command:
+
+```
+forge deploy template <path/to/project>
+```
+
+Note that you _must_ have the [Timoni CLI](https://timoni.sh/install/) installed locally for this command to work.
+Forge will automatically generate the Timoni bundle and then call the Timoni CLI to convert it to its raw YAML counterpart.
+The resulting manifests will then be printed to `stdout`.
+This is useful for troubleshooting a deployment as it allows you to examine exactly what is getting deployed to Kubernetes.