Skip to main content

Quickstart

caution

This project is currently in Beta. Please send us feedback!

info

Remember that to run this solution you will need at least:

  • 4 CPU cores
  • 8 GB RAM - It might be required to increase the Docker limits so it can use more RAM or Swap to run all components
  • 16 GB Disk space

Those numbers are not written in stone so your mileage may vary depending on which components you choose to install.

Prerequisites​

ToolsPurposeReference
asdfWe use the asdf version manager to install the tools needed for the Initium Platform.Install
ngrokUsed only for local testing to expose the services to the internet so the Github Actions workflows can reach the platform.Install
makeUsed to install all the required tools for Initium Platform.Install
dockerContainer engine used for Kubernetes.Install

Kubernetes Cluster​

Initium Platform will run in a Kubernetes cluster you already have provisioned, or, if you haven't one available or need some guidance, we have preparared the essential guidance to get you started in the most popular cloud providers:

Prepare the Platform​

  1. In a dedicated terminal, clone the platform repository on your local machine:

    git clone https://github.com/nearform/initium-platform.git

  2. Install the required tooling:

    cd initium-platform
    make asdf_install

  3. Start the platform:

    make

  4. Wait for the platform to be ready, then keep this dedicated terminal open.

    Access the Tilt interface following the instructions in your terminal and wait for the initium-platform to be ready as for the image below:

    Tilt Initium platform component

  5. Open a new terminal and create the service account for the applications:

    initium init service-account | kubectl apply -f -

Deploy your Demo application​

caution

We will be deploying this application using Github Actions via the Github registry.

The action's GITHUB_TOKEN will need workflow read and write permissions. You can find the instructions to set those up in Github's official documentation.

  1. Export the required secrets from your running platform:

    export INITIUM_CLUSTER_ENDPOINT=$(kubectl config view -o jsonpath='{.clusters[?(@.name == "kind-initium-platform")].cluster.server}')
    export INITIUM_CLUSTER_TOKEN=$(kubectl get secrets initium-cli-token -o jsonpath="{.data.token}" | base64 -d)
    export INITIUM_CLUSTER_CA_CERT=$(kubectl get secrets initium-cli-token -o jsonpath="{.data.ca\.crt}" | base64 -d)

  2. Open a new terminal and use ngrok to make the cluster accessible, allowing Github actions to connect to your local platform:

    ngrok tcp --region us $(kubectl config view -o jsonpath='{.clusters[?(@.name == "kind-initium-platform")].cluster.server}' | awk -F: '{print $NF}')

  3. Create a demo repository by following the Initum NodeJS demo app template link.

  4. Clone your new initium-nodejs-demo-app demo repository to your local computer.

  5. Switch to the directory of the local clone:

    cd initium-nodejs-demo-app

  6. Create the following GitHub secrets in your repository, either through the Github UI or using the Github CLI.

    Github UI

    Follow these instructions to create the secrets in Github UI.

    • CLUSTER_CA_CERT with its value set to the output of:

      echo $INITIUM_CLUSTER_CA_CERT

    • CLUSTER_TOKEN with its value set to the output of:

      echo $INITIUM_CLUSTER_TOKEN

    • CLUSTER_ENDPOINT with its value set to the ngrok endpoint from the command you ran in step 2, in the format:

      #.tcp.ngrok.io:PORT

      Note: There's no need to add the protocol to the CLUSTER_ENDPOINT variable, just the URL and the port. See the example below, where tcp was removed:

      ngrok URL: "tcp:#.tcp.ngrok.io:PORT"
      CLUSTER_ENDPOINT="#.tcp.ngrok.io:PORT"

    Github CLI

    • Make sure you have the Github CLI tool installed in your local computer.
    • Log in your Github account:
    gh auth login
    • Create the secrets 
    echo $INITIUM_CLUSTER_CA_CERT | gh secret set CLUSTER_CA_CERT
    echo $INITIUM_CLUSTER_TOKEN | gh secret set CLUSTER_TOKEN

    #CLUSTER_ENDPOINT value must be in the format: #.tcp.ngrok.io:PORT eg, 0.tcp.ngrok.io:1000 as in step 2 
    echo "#.tcp.ngrok.io:PORT" | gh secret set CLUSTER_ENDPOINT
    • Check that the secrets have been correctly created:
    gh secret list

  7. Expose the load balancer endpoint.

  • If your Docker network is reachable:

    export INITIUM_LB_ENDPOINT="$(kubectl get service -n istio-ingress istio-ingressgateway -o go-template='{{(index .status.loadBalancer.ingress 0).ip}}'):80"

  • If your Docker network is not reachable:

    kubectl port-forward service/istio-ingressgateway -n istio-ingress 8080:80 &
    export INITIUM_LB_ENDPOINT="127.0.0.1:8080"

  1. Initialise your clone repo:

    git checkout -b test && \
    asdf install && \
    initium init config --persist && \
    initium init github

  2. Commit and push the changes:

    git add .
    git commit -m "Initium start"
    git push -u origin test

  3. Open a PR in Github UI. This will trigger the associated Github actions.

  4. Once the Github actions are successful, you should see a Hello, World! message in your terminal running:

    curl -H "Host: initium-nodejs-demo-app.initium-test.example.com" $INITIUM_LB_ENDPOINT

  5. Merge the PR. Once the Github actions are done, check your running demo app:

    curl -H "Host: initium-nodejs-demo-app.main.example.com" $INITIUM_LB_ENDPOINT

  6. 🎉 You can open as many PRs as you want and have a separate environment for each one of them. You'll find the application endpoint in the output of the Github Action (work in progress).

Last updated on