add dev guides

docs/developer-guides/dependencies.md

@@ -0,0 +1,101 @@
+# Partner Chain Dependencies
+
+For a local cluster of nodes we need to have the dependencies running.
+The main chain follower reads from **postgres** that **db-sync** writes to.
+**db-sync** itself requires UDS connection to **cardano-node**.
+
+For executing **partner-chains-smart-contracts** CLI commands **ogmios** and **kupo** are required.
+Both of them open HTTP ports that `sidechain-main-cli` is looking for by default (1337 and 1442).
+
+This document will help you with spinning up the dependencies running in either docker; or
+_process-compose_; the latter utilizing containerless, natively built binaries via nix.
+
+## Using docker
+
+This section uses **cardano-node**, **cardano-db-sync** from ghcr.io repository,
+and **postgres**, **kupo**, and **ogmios** from docker.io repository.
+Setup uses docker volumes for cardano-node data, postgres data and substrate node data, and
+**cardano-node** Unix domain socket for **cardano-db-sync**.
+
+### Docker-compose
+
+The set-up of dependencies is maintained in the docker compose file.
+If you opt to run images individually, please use this file as reference for images configuration.
+
+To start the dependencies, from the root directory of this project, run:
+```
+docker-compose -f docker/sidechain-dependencies/docker-compose.yml up -d
+```
+
+### Docker settings for Apple Silicon
+
+- General
+  - Use Virtualization framework
+  - VirtioFS file sharing system
+- Resources
+  - CPUs: 5
+  - Memory: 12 GB
+- Features in development
+  - Use Rosetta for x86/amd64 emulation on Apple Silicon
+
+## Using the containerless nix stack
+
+To run the dependency stack without requiring OCI images we have an alternate
+implementation that utilizes
+[process-compose](https://github.com/F1bonacc1/process-compose) and nix shells.
+
+Benefits:
+
+- Access to the ECR not required; no images/containers are used to run the stack
+- Thus, no need to build/load/share images
+- Native local builds for each supported architecture:
+  - x86_64-linux
+  - x86_64-darwin
+  - arm64-darwin
+- Works as expected while connecting/disconnecting with the VPN
+
+### Setup and run
+To enter the shell with this stack setup using direnv, add an .envrc.local file with contents:
+```sh
+export NIX_SHELL=".#process-compose"
+```
+
+Then run:
+```sh
+direnv allow
+```
+
+You will get a new menu command: `sidechains-stack`. The command is a wrapper to
+the normal `process-compose` command, so check the `--help` for additional
+command line options (such as `--tui=false`).
+
+The data for the stack is output locally to the `.run` directory from where the
+command is launched.  This may change or be adjusted in the future to match with
+the data in docker-compose.  In addition, be aware that you should launch it in
+the same project (root) directory or it will create a new `.run` from your
+current `pwd`.
+
+### Other notes and features
+
+Process-compose runs an http server with swagger, and by default in this setup
+runs it on port `8081`.  You can attach to remote process-compose stacks with:
+```sh
+sidechains-stack attach --address <ip(default localhost)> --port 8081
+```
+You can also access the swagger UI through the browser e.g. by visiting
+`127.0.0.1:8081`
+
+## Forwarding Ports using Kubernetes
+
+Running the dependencies locally can often be avoided by forwarding ports from the pods deployed to our devnet.
+This can be done by running:
+```sh
+kubectl port-forward devnet-services -n sc 1337 1337
+kubectl port-forward devnet-services -n sc 1442 1442
+```
+to expose Ogmios and Kupo ports from the devnet-services pod.
+
+```sh
+kubectl port-forward dave -n sc 5432 5432
+```
+to expose Postgres port from the dave pod.

docs/developer-guides/getting-started.md

@@ -0,0 +1,121 @@
+# Getting started
+
+This is a guide for partner chains developers to get started in the project. When you complete it, you should be able to build the project, test locally, and access development environment hosted in EKS.
+
+Prerequisites:
+* `nix` installed
+* `docker` installed
+* `protoc` installed [link](https://google.github.io/proto-lens/installing-protoc.html)
+
+## Nix
+
+The development shells use Nix with flakes enabled. It should provide the most
+important tools (besides `docker`), to work in this project: `cargo` for
+building the project, and `aws` and `kubectl` to interact with the development
+environment.
+
+[Install a recent version of Nix](https://zero-to-nix.com/start/install), and
+use it to enter the project shell, preferably with [`direnv`](#direnv-support),
+but `nix develop` will also work.
+
+In order for nix to access our private repositories, it needs to be aware of a
+github token. Create a `.netrc` file in your home directory with the following
+content:
+```
+machine github.com
+login <GITHUB_LOGIN>
+password <GITHUB_TOKEN>
+
+machine api.github.com
+login <GITHUB_LOGIN>
+password <GITHUB_TOKEN>
+```
+
+`GITHUB_TOKEN` should have following permissions:
+- repo (full)
+- read:org
+
+It is recommended to add at least the following snippet to your
+`/etc/nix/nix.conf` for all methods:
+```
+extra-experimental-features = nix-command flakes
+netrc-file = /home/<USERNAME>/.netrc
+```
+
+
+After the token is setup, move to this project's directory and allow direnv to
+read the `.envrc` file:
+```
+# if you need to enable direnv on the project for the first time
+direnv allow
+
+# or reload it if the nix content has changed
+direnv reload
+```
+
+Build the project, to verify Rust toolchain is available:
+```
+cargo build
+```
+
+
+## Direnv support
+
+For those using [direnv](https://direnv.net/), you may choose to use it to enter
+the Nix shell since it not only allows you to use your shell of choice, but it
+will also load the environmental variables used in development of this project.
+
+It is highly recommended that you use this route not only for the
+above-mentioned benefits, but because it will allow your shell to survive a
+garbage collection, making entering it super quick after the initial build.
+
+## AWS Account
+
+To work with the Kubernetes cluster hosting developers environment,
+a user created in AWS Account 689191102645 is required.
+Terraform files controlling the environment are placed in the **sidechains-infra-priv**
+repository. To get a user, create a PR to the **master** branch, it should contain
+the entry with GPG public key and group assignment.
+See https://github.com/input-output-hk/sidechains-infra-priv/pull/36 for reference.
+When your PR is merged and terraform applied, SREs should give you the
+first password for your user.
+Log in https://eu-central-1.console.aws.amazon.com/console/home?region=eu-central-1#
+and change it.
+
+## AWS and EKS
+
+Setup AWS and EKS configuration files.
+
+1. Log in to AWS web console, from "user menu" go to "Security credentials",
+   and create Access Keys, then setup ~/.aws/credentials file using **Long-term credentials**
+   tab of this guide: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html.
+2. kubectl config: https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html
+```
+aws eks update-kubeconfig --region eu-central-1 --name iog-sidechain-substrate-kubernetes
+# test
+kubectl get pods -n sc
+```
+3. To log in into ECR, to pull or push images hosted there, run following command:
+```
+aws ecr get-login-password --region eu-central-1 | docker login --username AWS --password-stdin 689191102645.dkr.ecr.eu-central-1.amazonaws.com
+```
+
+## Testing locally
+
+To be able to test your changes locally, you need some number of nodes running locally, depending on how much functionality is tested. One node for a smoke test, checking if application reads configuration properly. Two nodes are required for block production.
+
+Command below show how to run a node locally:
+```
+./target/debug/sidechains-substrate-node --alice --base-path .run/data/alice --chain local --validator --node-key 0000000000000000000000000000000000000000000000000000000000000001  --port 30033 --rpc-port 3333 --unsafe-rpc-external --rpc-cors=all --state-pruning archive --blocks-pruning archive
+```
+`--alice` is one of special flags, that adhere to keys we usually use on devnet.
+Others are bob, charlie, dave, eve, ferdie and greg.
+`--chain local` makes node use the Local Testnet chain specification (chain_spec.rs file).
+`--node-key` please use from 1 to N with 0s prefix.
+`--state-pruning archive --blocks-pruning archive` are important, to test all endpoints we need
+archive nodes.
+
+Nodes read configuration from environment. `.envrc` file in this repository should be in-sync
+with partner chain used by devnet, which usually is an initialized and running chain. Devnet partner chains can sometimes be used to test committee-rotation. For more extensive testing one should [create their own partner chain on the main chain](./user-guides/chain-builder.md). Then [run the required dependencies](dependencies.md) and test the system.
+
+Please update partner-chains-smart-contracts revision in flake.nix, if your changes need a different version of partner-chains-smart-contracts than currently committed.