Release 0.0.2 : update docs, add (temporary) release procedure (#15)

* feat: update docs, add (temporary) release procedure

* fix: add tag step

* fix: improve release steps

.github/workflows/publish.yml

@@ -8,29 +8,9 @@ env:
   GO_VERSION: ~1.22
 
 jobs:
-  build:
-    name: Build operator image
-    runs-on: ubuntu-latest
-    outputs:
-      image_tag: ${{ steps.meta.outputs.version }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install Go
-        uses: actions/setup-go@v5
-        with:
-          go-version: ${{ env.GO_VERSION }}
-          check-latest: true
-
-      - name: Build
-        run: make docker-build IMG=drpsychick/mailu-operator:latest
-
   publish:
-    if: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
     name: Build and publish operator image
     runs-on: ubuntu-latest
-    needs: build
     outputs:
       image_tag: ${{ steps.meta.outputs.version }}
     permissions:
@@ -52,8 +32,7 @@ jobs:
           images: |
             drpsychick/mailu-operator
           tags: |
-            type=sha
-            type=ref,event=pr
+            type=ref,event=branch
             type=semver,pattern={{version}}
 
       - name: Set up QEMU
@@ -68,23 +47,27 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
+      # pushes a) "main" or b) $TAG+"latest"
       - name: Build and push
-        run: make docker-buildx IMG=drpsychick/mailu-operator:${{ steps.meta.outputs.version }} VERSION=${{ steps.meta.outputs.version }}
-
-      - name: Build operator install manifest
         env:
-          RELEASE_VERSION: ${{ steps.meta.outputs.version }}
-        run: |
-          make build-installer IMG=drpsychick/mailu-operator:${{ steps.meta.outputs.version }} VERSION=${{ steps.meta.outputs.version }}
+          VERSION: ${{ steps.meta.outputs.version }}
+        run: make docker-buildx
 
-      - name: Commit operator install manifest
-        uses: stefanzweifel/git-auto-commit-action@v5
-        with:
-          file_pattern: 'dist/*.yaml'
+# main branch must contain the latest install.yaml already with the right tag ("main" or $TAG)
+#      - name: Build operator install manifest
+#        env:
+#          VERSION: ${{ steps.meta.outputs.version }}
+#        run: |
+#          make build-installer
+#
+#      - name: Commit operator install manifest
+#        uses: stefanzweifel/git-auto-commit-action@v5
+#        with:
+#          file_pattern: 'dist/*.yaml'
 
+      # pushing a tag will trigger this
       - name: Release
         uses: softprops/action-gh-release@v2
         if: startsWith(github.ref, 'refs/tags/')
         with:
-          files: dist/install.yaml
           generate_release_notes: true

Makefile

@@ -29,7 +29,7 @@ BUNDLE_METADATA_OPTS ?= $(BUNDLE_CHANNELS) $(BUNDLE_DEFAULT_CHANNEL)
 #
 # For example, running 'make bundle-build bundle-push catalog-build catalog-push' will build and push both
 # mailu.io/mailu-operator-bundle:$VERSION and mailu.io/mailu-operator-catalog:$VERSION.
-IMAGE_TAG_BASE ?= mailu.io/mailu-operator
+IMAGE_TAG_BASE ?= drpsychick/mailu-operator
 
 # BUNDLE_IMG defines the image:tag used for the bundle.
 # You can use it as an arg. (E.g make bundle-build BUNDLE_IMG=<some-registry>/<project-name-bundle>:<tag>)
@@ -50,7 +50,7 @@ endif
 # This is useful for CI or a project to utilize a specific version of the operator-sdk toolkit.
 OPERATOR_SDK_VERSION ?= v1.36.1
 # Image URL to use all building/pushing image targets
-IMG ?= mailu-operator:latest
+IMG ?= drpsychick/mailu-operator:$(VERSION)
 # ENVTEST_K8S_VERSION refers to the version of kubebuilder assets to be downloaded by envtest binary.
 ENVTEST_K8S_VERSION = 1.29.0
 

README.md

@@ -110,21 +110,48 @@ Aliases are used to route emails for multiple email addresses to a user (email)
 
 As this project is brand new and in alpha stage, here are the current steps to try it out:
 
+1. get and apply the `install.yaml` which contains the CRDs and the deployment of the operator.
+2. edit the deployment to configure `MAILU_API` and `MAILU_TOKEN` environment variables.
+3. create `Domain`, `User` and `Alias` resources that will be applied to your Mailu instance.
+
+```shell
+LATEST=https://raw.githubusercontent.com/SickHub/mailu-operator/main/dist/install.yaml
+RELEASE=https://raw.githubusercontent.com/SickHub/mailu-operator/v0.0.2/dist/install.yaml
+NAMESPACE=mailu
+kubectl apply -n $NAMESPACE -f $RELEASE
+
+# edit the deployment and set your Mailu API url and token
+kubectl -n $NAMESPACE edit deployment mailu-operator-controller-manager
+
+# now you can add Domain, User and Alias resources
+kubectl apply -n $NAMESPACE -f config/samples/operator_v1alpha1_domain.yaml
+kubectl apply -n $NAMESPACE -f config/samples/operator_v1alpha1_user.yaml
+kubectl apply -n $NAMESPACE -f config/samples/operator_v1alpha1_alias.yaml
+
+# remove the operator again
+kubectl delete -n $NAMESPACE -f $RELEASE
+```
+
+Build and install the operator from your fork:
 ```shell
 REGISTRY=<your-registry>
+NAMESPACE=mailu
 # 1. build the image and push it to your own registry
-make docker-buildx IMG=$REGISTRY/mailu-operator:v0.0.1
+make docker-buildx IMG=$REGISTRY/mailu-operator:dev
 
 # 2. build the `install.yaml` used to deploy the operator (including CRDs, Roles and Deployment)
-make build-installer IMG=$REGISTRY/mailu-operator:v0.0.1
+make build-installer IMG=$REGISTRY/mailu-operator:dev
 
 # 3. apply the `install.yaml` to your k8s cluster
-kubectl apply -f dist/install.yaml
+kubectl apply -n $NAMESPACE -f dist/install.yaml
+
+# 4. edit the `MAILU_API` and `MAILU_TOKEN` environment variables
+kubectl -n $NAMESPACE edit deployment mailu-operator-controller-manager
 ```
 
-Uninstall
+Uninstall the operator
 ```shell
-kubectl delete -f dist/install.yaml
+kubectl delete -n $NAMESPACE -f dist/install.yaml
 ```
 
 ## Development: Build and deploy on your cluster
@@ -172,6 +199,7 @@ kubectl apply -k config/samples/
 >**NOTE**: Ensure that the samples has default values to test it out.
 
 ### To Uninstall
+
 **Delete the instances (CRs) from the cluster:**
 
 ```sh
@@ -190,49 +218,34 @@ make uninstall
 make undeploy
 ```
 
-## Project Distribution
+## Releasing / Project Distribution
 
 Following are the steps to build the installer and distribute this project to users.
+It is generally advised to **create a fork** of the repo and create Pull-Requests from your fork.
 
-1. Build the installer for the image built and published in the registry:
+1. Build the installer for the release tag:
+    ```sh
+    git checkout -b release-0.0.2
+    VERSION=0.0.2 make build-installer
+    ```
 
-```sh
-make build-installer IMG=<some-registry>/mailu-operator:tag
-```
+2. Create a Pull-Request on GitHub with the changes
+    - at least `dist/install.yaml` and `config/manager/kustomization.yaml` containing the latest tag
 
-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.
+3. Get the Pull-Request reviewed/approved and merged
+    - the image will be built and pushed to docker hub
+    - a release with be created with generated release notes
 
-2. Using the installer
-
-Users can just run kubectl apply -f <URL for YAML BUNDLE> to install the project, i.e.:
-
-```sh
-kubectl apply -f https://raw.githubusercontent.com/<org>/mailu-operator/<tag or branch>/dist/install.yaml
-```
+4. Push the tag
+    ```shell
+    git checkout main
+    git tag v0.0.2
+    git push
+    ```
 
 ## Contributing
 // TODO(user): Add detailed information on how you would like others to contribute to this project
 
 **NOTE:** Run `make help` for more information on all potential `make` targets
 
 More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
-
-## License
-
-Copyright 2024.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-

config/manager/kustomization.yaml

@@ -4,5 +4,5 @@ apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 images:
 - name: controller
-  newName: mailu-operator
-  newTag: latest
+  newName: drpsychick/mailu-operator
+  newTag: 0.0.2

config/samples/operator_v1alpha1_user.yaml

@@ -7,21 +7,21 @@ metadata:
   name: user-sample
 spec:
   # --> email: $name@$domain
+  name: test
+  domain: example.com
   # allowSpoofing: false
   changePassword: false
   comment: "test user"
   displayedName: "[email protected]"
-  domain: example.com
   enabled: true
   enableIMAP: false
   enablePOP: false
   # forwardEnabled: false
   # forwardDestination: "[email protected]"
   # forwardKeep: false
   # globalAdmin: false
-  name: test
   quotaBytes: -1
-  # rawPassword: "s3cr3t!"
+  rawPassword: "s3cr3t!"
   # passwordSecret: "mailu-users"
   # passwordKey: "[email protected]"
   # replyEnabled: false

dist/install.yaml

@@ -881,7 +881,7 @@ spec:
           value: http://mailu-front.mail:80/api/v1
         - name: MAILU_TOKEN
           value: asdf
-        image: drpsychick/mailu-operator:sha-f6c0e35
+        image: drpsychick/mailu-operator:0.0.2
         livenessProbe:
           httpGet:
             path: /healthz