From d82f9fa7889af32b181d6c4aca9152359c169fcd Mon Sep 17 00:00:00 2001 From: cheshire Date: Sun, 19 Nov 2023 14:47:59 +0100 Subject: [PATCH] doc/codelabs/getting-started: update tutorials --- ...g-web-app.md => building-flask-web-app.md} | 46 ++++---- ...-web-app.md => deploying-flask-web-app.md} | 26 +++-- .../getting-started/prepare-environment.md | 9 +- .../getting-started/run-first-service.md | 103 ------------------ doc/codelabs/index.md | 5 +- 5 files changed, 51 insertions(+), 138 deletions(-) rename doc/codelabs/getting-started/{building-web-app.md => building-flask-web-app.md} (56%) rename doc/codelabs/getting-started/{deploying-web-app.md => deploying-flask-web-app.md} (67%) delete mode 100644 doc/codelabs/getting-started/run-first-service.md diff --git a/doc/codelabs/getting-started/building-web-app.md b/doc/codelabs/getting-started/building-flask-web-app.md similarity index 56% rename from doc/codelabs/getting-started/building-web-app.md rename to doc/codelabs/getting-started/building-flask-web-app.md index 467fc471..c49c87f7 100644 --- a/doc/codelabs/getting-started/building-web-app.md +++ b/doc/codelabs/getting-started/building-flask-web-app.md @@ -4,16 +4,14 @@ In this chapter, we will build our own web service using the Flask framework, do ## Requirements -You will require `docker` in this example. Install it from your standard shell. +You will require `docker` in this example. You can find installation instructions [here](https://docs.docker.com/engine/install/). For example, on Ubuntu you can install it with: ```bash curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh ``` -You can actually create, build and register docker image in completely other environment, and just deploy it to kubernetes in hscloud environment. - -It is advised to have done [Run first service](run-first-service.md) chapter. +To create, build and register docker image you don't need a compiled hscloud environment, howerver you will need it to deploy the image to kubernetes. ## Steps @@ -35,8 +33,21 @@ if __name__ == '__main__': app.run() ``` -We can check if the application works by running it: +We can check if the application works by running it. First we start the virtual environment and install Flask: +```bash +# for Linux and macOS environments +python3 -m venv .venv +source .venv/bin/activate +``` + +```bash +# for Windows environments +py -m venv .venv +.venv\bin\Activate.bat +``` + +After that: ```bash pip3 install flask python3 app.py @@ -46,7 +57,7 @@ Now we create `Dockerfile` file for our application: ```Dockerfile # Use an official Python runtime as a base image -FROM python:3.8-slim-buster +FROM python:3.12.0-bullseye # Set the working directory in docker WORKDIR /app @@ -72,15 +83,15 @@ CMD ["gunicorn", "-w", "4", "-b", ":5000", "app:app"] We can test if the application works in Docker: ```bash -docker build -t myflask . # Build the image -docker run -d -p 5000:5000 myflask # Run the container +docker build -t myflask:2137 . # Build the image +docker run -p 5000:5000 myflask:2137 # Run the container ``` We can check if the application works by opening the browser at `http://localhost:5000`. ## Pushing the image to the registry -First, we need to authenticate to the registry: +First, we need to authenticate to the registry. That will require visiting the link in a web browser: ``` https://registry.k0.hswaw.net @@ -92,26 +103,23 @@ You should get command similar to: docker login -u $hs_username -p *************** https://registry.k0.hswaw.net ``` +Run it in your environment. Now we need to create local server for our docker image: ```bash -docker tag myflask registry.k0.hswaw.net/$hs_username/myflask:latest -docker push registry.k0.hswaw.net/$hs_username/myflask:latest -``` - -To check if the image is in the registry, you can use: - -```bash -curl -X GET https://registry.k0.hswaw.net/v2/$hs_username/myflask/tags/list +# create local server for our docker image. Replace $hs_username with your sso username +docker tag myflask:2137 registry.k0.hswaw.net/$hs_username/myflask:2137 +docker push registry.k0.hswaw.net/$hs_username/myflask:2137 ``` To remove the image from the registry, you can use: ```bash -docker rmi registry.k0.hswaw.net/$hs_username/myflask:latest +# remove image from registry. Replace $hs_username with your sso username +docker rmi registry.k0.hswaw.net/$hs_username/myflask:2137 ``` ## Next step -[Deploying web app](deploying-web-app.md) \ No newline at end of file +[Deploying Flask web app](deploying-flask-web-app.md) \ No newline at end of file diff --git a/doc/codelabs/getting-started/deploying-web-app.md b/doc/codelabs/getting-started/deploying-flask-web-app.md similarity index 67% rename from doc/codelabs/getting-started/deploying-web-app.md rename to doc/codelabs/getting-started/deploying-flask-web-app.md index 918326dd..b8e9cac7 100644 --- a/doc/codelabs/getting-started/deploying-web-app.md +++ b/doc/codelabs/getting-started/deploying-flask-web-app.md @@ -4,20 +4,19 @@ In this chapter, we will deploy our registered docker image on `hscloud` as a si ## Requirements -Registered image from [Building web app](building-web-app.md): - -``` -https://registry.k0.hswaw.net/$hs_username/myflask:latest -``` +Registered image from [Building web app](building-web-app.md). Also, built `hscloud` environment from [Building an environment](prepare-environment.md) section. ## Steps -We create a `prod.jsonnet` file in location `//personal/$hs_username/myflask/prod.jsonnet`: +We create a `prod.jsonnet` file in location `//personal/$hs_username/myflask/prod.jsonnet`. +The format of `jsonnet` is very similar to `json`, but allows the use of variables, functions, and the import of other files. +For further reference on `jsonnet` see [jsonnet.org](https://jsonnet.org/learning/tutorial.html). ```jsonnet # Remember to replace $hs_username with your SSO username! +# The import is done from the `kube.libsonnet` file in the `kube` folder in the `hscloud` folder. local kube = import "../../../kube/kube.libsonnet"; { @@ -26,9 +25,11 @@ local kube = import "../../../kube/kube.libsonnet"; cfg:: { name: 'web-app', + # The hscloud configuration only allows the namespace in `personal-$hs_username` format. namespace: 'personal-$hs_username', + # The hscloud configuration only allows the domain in `*.$hs_username.hscloud.ovh` format. domain: 'web-app.$hs_username.hscloud.ovh', - image: 'registry.k0.hswaw.net/$hs_username/myflask:latest', + image: 'registry.k0.hswaw.net/$hs_username/myflask:2137', }, ns: kube.Namespace(cfg.namespace), @@ -80,16 +81,23 @@ local kube = import "../../../kube/kube.libsonnet"; } ``` +We log into the cluster: + +```bash +hs_username=$USER # if your username is the same as your SSO username +prodaccess -username $hs_username +``` + We can now deploy our application: ```bash kubecfg update prod.jsonnet ``` -The application should be available at `http://web-app.$hs_username.hscloud.ovh`. You will have to wait several seconds for the working HTTPS service. +The application should be available at `http://web-app.$hs_username.hscloud.ovh`. You will have to wait a few minutes for a working HTTPS service. To remove the application, execute: ```bash -kubecfg delete prod.jsonnet +kubectl delete service test -n personal-$hs_username ``` \ No newline at end of file diff --git a/doc/codelabs/getting-started/prepare-environment.md b/doc/codelabs/getting-started/prepare-environment.md index f50aab30..a1439e9c 100644 --- a/doc/codelabs/getting-started/prepare-environment.md +++ b/doc/codelabs/getting-started/prepare-environment.md @@ -27,7 +27,7 @@ chmod +x .git/hooks/commit-msg ## Steps -We can configure the environment using niix-shell. To do this, we install `nix`: +We can configure the environment using nix-shell. To do this, we install `nix`: ```bash sh <(curl -L https://nixos.org/nix/install) --daemon @@ -46,14 +46,15 @@ bazel build //tools:install bazel run //tools:install ``` -Now we can request to grant us access to the hscloud cluster through the [prodaccess](https://pkg.go.dev/code.hackerspace.pl/hscloud/cluster/prodaccess#section-readme) tool. In place of `$hs_username` insert the username in SSO hackerspace: +Now we can request to grant us access to the hscloud cluster through the [prodaccess](https://pkg.go.dev/code.hackerspace.pl/hscloud/cluster/prodaccess#section-readme) tool. +In place of `$hs_username` insert the username in SSO hackerspace: ```bash hs_username=$USER # if your username is the same as your SSO username prodaccess -username $hs_username ``` -If you do not have access to the cluster, contact [@q3k](q3k:hackerspace.pl) or [@inf](informatic:hackerspace.pl) within [Matrix](https://matrix.hackerspace.pl/). +If you do not have access to the cluster, contact someone within [Matrix #infra channel](https://matrix.to/#/#infra:hackerspace.pl). To check if we have access to the cluster, we can run the command: @@ -81,4 +82,4 @@ kubectl -n personal-$hs_username delete pod foo ## Next step -Next step: [Run first service](run-first-service.md) \ No newline at end of file +Next step: [Building Flask web app](building-flask-web-app.md) \ No newline at end of file diff --git a/doc/codelabs/getting-started/run-first-service.md b/doc/codelabs/getting-started/run-first-service.md deleted file mode 100644 index 33610d23..00000000 --- a/doc/codelabs/getting-started/run-first-service.md +++ /dev/null @@ -1,103 +0,0 @@ -# Running a public service in hscloud - -In this chapter, I will show you how to run an existing service that will be publicly available on the Internet. - -## Requirements - -Done steps from [**Prepare environment**](prepare-environment.md) chapter. - -## Creating a copy of ldapweb - -We start in the `hscloud` folder, with the `nix-shell` environment enabled. If you don't have your namespace in the `//personal` folder yet, we create it: - -```bash -mkdir personal/$hs_username -``` - -We copy the configuration of the `ldapweb` service into the workspace: - -```bash -cp -r hswaw/ldapweb/ personal/$hs_username/ -cd personal/$hs_username/ldapweb/ -``` - -## Modifying the service - -The configuration of `ldapweb` is contained in the `prod.jsonnet` file. The format of `jsonnet` is very similar to `json`, but allows the use of variables, functions, and the import of other files. - -We are interested in the initial part of the file: - -```jsonnet -local kube = import "../../kube/kube.libsonnet" - -{ - local top = self, - local cfg = self.cfg, - - cfg:: { - name: 'ldapweb', - namespace: 'ldapweb', - domain: 'profile.hackerspace.pl', - image: 'registry.k0.hswaw.net/radex/ldap-web:1695486391', - }, -... -} -``` - -The import is done from the `kube.libsonnet` file in the `kube` folder in the `hscloud` folder. In order for the import to proceed correctly in this case, we need to go back one more folder: `../../../kube/kube.libsonnet`. - -The `hscloud` configuration only allows the namespace in `personal-$hs_username` format. In addition, we need to change the domain to `*.$hs_username.hscloud.ovh`. Finally, we change the service name to `test`. - -Finally, the above fragment of the `prod.jsonnet` file should look like this: - - -```jsonnet -# remember to replace $hs_username with your username! - -local kube = import "../../../kube/kube.libsonnet"; - -{ - local top = self, - local cfg = self.cfg, - - - cfg:: { - name: 'test', - namespace: 'personal-$hs_username', - domain: 'test.$hs_username.hscloud.ovh', - image: 'registry.k0.hswaw.net/radex/ldap-web:1695486391', - }, -... -} -``` - -We log into the cluster: - -```bash -hs_username=$USER # if your username is the same as your SSO username -prodaccess -username $hs_username -``` - -We invoke the command to apply the changes: - -```bash -kubecfg update prod.jsonnet -``` - -Our service should be at `https://test.$hs_username.hscloud.ovh/`. During the first couple of minutes we will get a message about an invalid certificate, because the Let's Encrypt service has not yet managed to generate a certificate for our domain. - -To remove the service, call: - -```bash -kubecfg delete prod.jsonnet -``` - -or - -```bash -kubectl delete service test -n personal-$hs_username -``` - -## Next step - -[Building web app](building-web-app.md) \ No newline at end of file diff --git a/doc/codelabs/index.md b/doc/codelabs/index.md index b0b6dc8d..311d3a0b 100644 --- a/doc/codelabs/index.md +++ b/doc/codelabs/index.md @@ -12,9 +12,8 @@ Getting started - [**Your First Change**](getting-started/your-first-change.md) - how to use Gerrit and git to send your first change to hscloud, and an intro to personal directories. Using Gerrit can be somewhat confusing even (or especially) if you're used to Gitflow or GitHub. - [**Bazel & Go basics**](getting-started/bazel-go.md) - will (TODO) guide you through building some code using Bazel, and then writing a tiny bit of Go code of your own. - [**Preparing kubernetes environment**](getting-started/prepare-environment.md) - how to build environment using `nix` and `bazel`, to be able to run first kubernetes pod. -- [**Creating test pod**](getting-started/run-first-service.md) - how to deploy first service from available image. -- [**Building web app**](getting-started/building-web-app.md) - how to prepare our first Flask app and register it on hscloud k8s registry. -- [**Deploying web app**](getting-started/deploying-web-app.md) - how to deploy our registed web app. +- [**Building web app**](getting-started/building-flask-web-app.md) - how to prepare our first Flask app and register it on hscloud k8s registry. +- [**Deploying web app**](getting-started/deploying-flask-web-app.md) - how to deploy our registed Flask web app on hscloud. See also --------