From eec447a94eaa4e52bbb9e2bb5975c2684bfc2418 Mon Sep 17 00:00:00 2001
From: cheshire <cheshire@hackerspace.pl>
Date: Sat, 14 Oct 2023 12:30:04 +0200
Subject: [PATCH] :cat: Add instructions for ubuntu and nixos

---
 01-prepare-nixos.md     | 33 ++++++++++++++++++++++++++
 01-prepare-ubuntu.md    | 32 +++++++++++++++++++++++++
 02-build-environment.md | 52 +++++++++++++++++++++++++++++++++++++++++
 README.md               | 11 ++++++++-
 4 files changed, 127 insertions(+), 1 deletion(-)
 create mode 100644 01-prepare-nixos.md
 create mode 100644 01-prepare-ubuntu.md
 create mode 100644 02-build-environment.md

diff --git a/01-prepare-nixos.md b/01-prepare-nixos.md
new file mode 100644
index 0000000..a02dbcb
--- /dev/null
+++ b/01-prepare-nixos.md
@@ -0,0 +1,33 @@
+# Kompilacja w środowisku NixOS
+
+NixOS jest systemem operacyjnym, który pozwala na deklaratywne opisywanie środowiska. W tym rozdziale opisane są kroki potrzebne do zbudowania środowiska, w którym można budować usługi w chmurze.
+
+W tym tutorialu została wykorzystana wersja NixOS 23.05.
+
+Skrypt wykonujący dostępny w [01-build-nixos.sh](01-build-nixos.sh) wykonuje wszystkie kroki opisane w tym rozdziale.
+
+Całość opisu opiera się na informacjach uzyskanych z rozmów oraz z [dokumentacji użytkownika hscloud](https://code.hackerspace.pl/hswaw/hscloud/src/branch/master/cluster/doc/user.md).
+
+## Wymagania
+
+Chęć do zainstalowania NixOSa, bare metal lub wirtualnie. Wirtualizacja może być wykonana np. za pomocą [VirtualBox](https://www.virtualbox.org/).
+
+## Kroki
+
+Pobierz system NixOS z [nixos.org](https://nixos.org/download.html#nixos-iso) i zainstaluj go na swojej maszynie.
+
+Potrzebujemy zainstalować pakiet `git` i sklonować repozytorium z kodem źródłowym usług w chmurze. W terminalu wpisujemy:
+
+```bash
+nix-env -iA nixos.git
+git clone https://code.hackerspace.pl/hswaw/hscloud
+cd hscloud
+```
+
+Ze względu na drobny błąd, należy pozbyć się z `shell.nix` komendy kompilacji `clang`:
+
+```bash
+sed -i '/gcc binutils clang/s/clang//g' "shell.nix"
+```
+
+Następny krok: [Budowa środowiska](02-build-environment.md)
\ No newline at end of file
diff --git a/01-prepare-ubuntu.md b/01-prepare-ubuntu.md
new file mode 100644
index 0000000..55d1e57
--- /dev/null
+++ b/01-prepare-ubuntu.md
@@ -0,0 +1,32 @@
+# Kompilacja w środowisku Ubuntu
+
+W tym rozdziale opisane są kroki potrzebne do zbudowania środowiska, w którym można budować usługi w chmurze hscloud. Instrukcja wzoruje się na [01-build-nixos.md](01-build-nixos.md), jedynie z dodatkowym krokiem pobierania i instalacji menedżera pakietów `nix`.
+
+## Wymagania
+
+Uprawnienia administratora, środowisko Ubuntu 22.04 lub nowsze, bądź odpowiedni Ubuntu-like desktop.
+
+## Kroki
+
+Instalujemy pakiety `git` oraz `curl`:
+
+```bash
+sudo apt install git curl
+```
+
+Pobieramy i instalujemy menadżer pakietów `nix` (źródło: [nixos.org](https://nixos.org/download)):
+
+```bash
+sh <(curl -L https://nixos.org/nix/install) --daemon
+```
+
+Po tej operacji należy wylogować się i zalogować ponownie, aby móc korzystać z `nix`.
+
+Klonujemy repozytorium z kodem źródłowym usług w chmurze:
+
+```bash
+git clone https://code.hackerspace.pl/hswaw/hscloud
+cd hscloud
+```
+
+Następny krok: [Budowa środowiska](02-build-environment.md)
\ No newline at end of file
diff --git a/02-build-environment.md b/02-build-environment.md
new file mode 100644
index 0000000..5cff1b8
--- /dev/null
+++ b/02-build-environment.md
@@ -0,0 +1,52 @@
+# Budowa środowiska
+
+W tym rozdziale przedstawię, jak na przygotowanej już platformie (NixOS, Ubuntu, etc.) zbudować środowisko, w którym będziemy budować usługi w chmurze hscloud.
+
+## Kroki
+
+Ze względu na drobny błąd, należy pozbyć się z `shell.nix` komendy kompilacji `clang`:
+
+```bash
+sed -i '/gcc binutils clang/s/clang//g' "shell.nix"
+```
+
+Tworzymy środowisko, w którym będziemy budować usługi. W tym celu tworzymy środowisko na podstawie definicji w pliku `shell.nix`:
+
+```bash
+nix-shell
+```
+
+Używamy teraz narzędzia `bazel`, aby zbudować i uruchomić potrzebne usługi, m.in. `prodaccess` oraz `kubectl`:
+
+```bash
+bazel build //tools:install
+bazel run //tools:install
+```
+
+Teraz możemy poprosić o przyznanie nam dostępu do klastra hscloud poprzez narzędzie [prodaccess](https://pkg.go.dev/code.hackerspace.pl/hscloud/cluster/prodaccess#section-readme). w miejsce `$hs_username` należy wstawić nazwę użytkownika w SSO hackerspejsu:
+
+```bash
+prodaccess -u $hs_username
+```
+
+W przypadku braku dostępu do klastra, należy skontaktować się w ramach [Matrix](https://matrix.hackerspace.pl/) z [@q3k](q3k:hackerspace.pl) bądź z [@inf](informatic:hackerspace.pl).
+
+Aby sprawdzić, czy mamy dostęp do klastra, możemy wykonać polecenie:
+
+```bash
+# pokazuje wersję Kubernetesów
+kubectl version
+
+# pokazuje statystyki klastra
+kubectl top nodes
+```
+
+Możemy również wywołać publiczny obraz Dockera (ponownie, w miejsce `$USER` należy wstawić nazwę użytkownika w SSO hackerspejsu):
+
+```bash
+# aby utworzyć obraz
+kubectl -n personal-$hs_username run --image=alpine:latest -it foo
+
+# aby skasować obraz
+kubectl -n personal-$hs_username delete pod foo
+```
\ No newline at end of file
diff --git a/README.md b/README.md
index 2e656d8..8a1d03d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,12 @@
 # hscloud-docs
 
-Wprowadzenie do tworzenia usług w hscloud.
\ No newline at end of file
+Wprowadzenie do tworzenia usług w hscloud. Niniejszy zestaw dokumentów ma na celu dokumentację procesu wgryzania się w działanie chmury.
+
+## Przygotowanie środowiska
+
+- [Budowa na NixOS](01-prepare-nixos.md)
+- [Budowa na Ubuntu](01-prepare-ubuntu.md)
+
+## Przygotowywanie narzędzi
+
+- [Budowa środowiska](02-build-environment.md)
\ No newline at end of file