Update readme

README.md

@@ -1,98 +1,178 @@
 # fabricator
-// TODO(user): Add simple overview of use/purpose
 
-## Description
-// TODO(user): An in-depth paragraph about your project and overview of use
+Fabricator is the repo that holds the scripts and utilities used to build the
+fabric, VLAB, bare metal installers, helm charts, and pods that are used in the
+open network fabric.
 
-## Getting Started
+## Description 
+
+The components of this repository are distributed and versioned independently
+as OCI compliant artifacts.
+
+
+## Local Build Instructions
 
 ### Prerequisites
-- go version v1.22.0+
-- docker version 17.03+.
-- kubectl version v1.11.3+.
-- Access to a Kubernetes v1.11.3+ cluster.
+- go version v1.23.0+
+- docker version 17.03+. (used for logging into ghcr.io)
+- [zot v2.1.0](https://zotregistry.dev/v2.1.0/)
+- ghcr.io classic token with package **read** permissions
+- git
 
-### To Deploy on the cluster
-**Build and push your image to the location specified by `IMG`:**
+### Create a github Classic Token
 
-```sh
-make docker-build docker-push IMG=<some-registry>/fabricator:tag
-```
+1. Log into github.com 
+1. Click on your icon in the top right corner
+1. Click on settings (gear icon)
+1. On the left side of the page, scroll down and select "Developer Settings"
+1. On the left side click the drop down arrow of "Personal access tokens"
+1. Select "Tokens (classic)"
+1. On the next page, right of center near the top select "Generate new token"
+   drop down, then select "Generate new token (classic)"
+1. You will be prompted for a TOTP code
+1. Name your token according to your needs
+1. Select an expiration period of 60-90 days
+1. The Scope of the token should be **read** packages, only
+1. Click Generate token at the bottom of the page
+1. Copy the token down as it will only be visible on this page, it will be used
+   to configure `zot` in the following step
 
-**NOTE:** This image ought to be published in the personal registry you specified.
-And it is required to have access to pull the image from the working environment.
-Make sure you have the proper permission to the registry if the above commands don’t work.
 
-**Install the CRDs into the cluster:**
+### Install Zot
 
-```sh
-make install
-```
+Zot is an OCI package registry. Zot is used on your local system as a
+pull-through cache for all artifacts that are not being changed locally as part
+of development process.
 
-**Deploy the Manager to the cluster with the image specified by `IMG`:**
+[Zot installation
+instructions](https://zotregistry.dev/v2.1.0/install-guides/install-guide-linux/#installation)
 
-```sh
-make deploy IMG=<some-registry>/fabricator:tag
-```
+The installation instructions above are for the most part distribution
+agnostic. Some of the configuration files mentioned in the link are below:
 
-> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
-privileges or be logged in as admin.
+<details>
 
-**Create instances of your solution**
-You can apply the samples (examples) from the config/sample:
+This file:
+* creates a registry with data in `/tmp/zot`
+* runs a localhost only server on port 30000
+* mirrors everything from the githedgehog github repo
+
+<summary> /etc/zot/config.json </summary>
 
-```sh
-kubectl apply -k config/samples/
 ```
+{
+  "log": {
+    "level": "debug"
+  },
+  "storage": {
+    "rootDirectory": "/tmp/zot"
+  },
+  "http": {
+    "address": "127.0.0.1",
+    "port": "30000"
+  },
+  "extensions": {
+    "sync": {
+      "enable": true,
+      "credentialsFile": "/etc/zot/creds.json",
+      "registries": [
+        {
+          "urls": [
+            "https://ghcr.io"
+          ],
+          "onDemand": true,
+          "tlsVerify": true,
+          "content": [
+            {
+              "prefix": "/githedgehog/**",
+              "destination": "/githedgehog",
+              "stripPrefix": true
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
 
->**NOTE**: Ensure that the samples has default values to test it out.
+```
+</details>
 
-### To Uninstall
-**Delete the instances (CRs) from the cluster:**
+<details>
 
-```sh
-kubectl delete -k config/samples/
-```
+This file is supplying credentials for zot to read packages using your github
+account.
 
-**Delete the APIs(CRDs) from the cluster:**
+<summary>/etc/zot/creds.json</summary>
 
-```sh
-make uninstall
 ```
 
-**UnDeploy the controller from the cluster:**
+{
+  "ghcr.io": {
+    "username": "YOUR_USERNAME_HERE",
+    "password": "READ_ONLY_TOKEN_FROM_GITHUB"
+  }
+}
 
-```sh
-make undeploy
 ```
 
-## Project Distribution
+</details>
+
+<details>
 
-Following are the steps to build the installer and distribute this project to users.
+A systemd unit file for creating a zot registry.
 
-1. Build the installer for the image built and published in the registry:
+<summary>/etc/systemd/system/zot.service</summary>
 
-```sh
-make build-installer IMG=<some-registry>/fabricator:tag
+```
+[Unit]
+Description=OCI Distribution Registry
+Documentation=https://zotregistry.dev/
+After=network.target auditd.service local-fs.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/zot serve /etc/zot/config.json
+Restart=on-failure
+User=zot
+Group=zot
+LimitNOFILE=500000
+MemoryHigh=30G
+MemoryMax=32G
+
+[Install]
+WantedBy=multi-user.target
 ```
 
-NOTE: The makefile target mentioned above generates an 'install.yaml'
-file in the dist directory. This file contains all the resources built
-with Kustomize, which are necessary to install this project without
-its dependencies.
+</details>
 
-2. Using the installer
+A `zot` user will need to be created, per the link above.
 
-Users can just run kubectl apply -f <URL for YAML BUNDLE> to install the project, i.e.:
+### Just push
 
-```sh
-kubectl apply -f https://raw.githubusercontent.com/<org>/fabricator/<tag or branch>/dist/install.yaml
-```
+The fabricator repo uses a [justfile][justfile1] for building and deploying code. After
+you have made changes to your code, use
+`just oci=http push` to build and push your code. All OCI artifacts will be
+versioned using the [version string in tools.just][justfile2]
+and will be pushed to the zot registry on the local machine, the new binaries will be created in `./bin/`
+
+[justfile1]: https://github.com/githedgehog/fabricator/blob/21154b09112bdf148957dc75f2ce46d5be7beca0/justfile
+[justfile2]: https://github.com/githedgehog/fabricator/blob/21154b09112bdf148957dc75f2ce46d5be7beca0/hack/tools.just#L7
+
+### hhfab
+
+If the code you are changing deals with setting up or managing flatcar, hhfab
+will need to be instructed to pull packages from the local zot registry and not
+the ghcr. To do this, specify the repo pass the `--registry-repo
+127.0.0.1:30000` flag and argument to  `hhfab init` along with other flags.
+From there continue on with the `hhfab` commands. To get vlab running with
+local changes:
+* `hhfab init --dev --registry-repo 127.0.0.1`
+* `hhfab vlab gen`
+* `hhfab vlab up --mode iso`
 
-## Contributing
-// TODO(user): Add detailed information on how you would like others to contribute to this project
+### updating pods
 
-**NOTE:** Run `make help` for more information on all potential `make` targets
+* (TODO)
 
-More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)