From 33e443f41f040d9092386d727d6050bc1257094b Mon Sep 17 00:00:00 2001
From: Zach <zach@bluecollarcoding.ca>
Date: Wed, 27 Sep 2023 17:36:12 -0400
Subject: [PATCH] Gitea x Laconicd + some doc updates (#549)

* combine instructions from 2 stacks


Former-commit-id: 77d194cfd9b0503c3e55e8c79429fa1f36a8d784

* tidy doc

---------

Co-authored-by: zramsay <zach@bluecollacoding.ca>
---
 docs/README.md                                |  8 ++
 docs/cli.md                                   |  2 +-
 docs/gitea-with-laconicd-fixturenet.md        | 80 +++++++++++++++++++
 ...fixturenet.md => laconicd-with-console.md} |  0
 docs/spec.md                                  |  3 +-
 5 files changed, 90 insertions(+), 3 deletions(-)
 create mode 100644 docs/README.md
 create mode 100644 docs/gitea-with-laconicd-fixturenet.md
 rename docs/{laconicd-fixturenet.md => laconicd-with-console.md} (100%)

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..a3146301
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,8 @@
+# Stack Orchestrator
+
+Here you will find information about the design of stack orchestrator, contributing to it, and deploying services/applications that combine two or more "stacks".
+
+Most "stacks" contain their own README which has plenty of information on deploying, but stacks can be combined in a variety of ways which are document here, for example:
+
+- [Gitea with Laconicd Fixturenet](./gitea-with-laconicd-fixturenet.md)
+- [Laconicd Registry with Console](./laconicd-with-console.md)
diff --git a/docs/cli.md b/docs/cli.md
index 287d6c68..e9f06108 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -6,7 +6,7 @@ Sub-commands and flags
 
 Clone a single repository:
 ```
-$ laconic-so setup-repositories --include cerc-io/go-ethereum
+$ laconic-so setup-repositories --include github.com/cerc-io/go-ethereum
 ```
 Clone the repositories for a stack:
 ```
diff --git a/docs/gitea-with-laconicd-fixturenet.md b/docs/gitea-with-laconicd-fixturenet.md
new file mode 100644
index 00000000..f0b3e804
--- /dev/null
+++ b/docs/gitea-with-laconicd-fixturenet.md
@@ -0,0 +1,80 @@
+# Gitea x NPMs X Laconicd
+
+Deploy a local Gitea server, publish NPM packages to it, then use those packages to build a Laconicd fixturenet. Demonstrates several components of the Laconic stack
+
+### Build and Deploy Gitea
+
+```bash
+laconic-so --stack build-support build-containers
+laconic-so --stack package-registry setup-repositories
+laconic-so --stack package-registry build-containers 
+laconic-so --stack package-registry deploy up
+```
+
+These commands can take awhile. Eventually, some instructions and a token will output. Set `CERC_NPM_AUTH_TOKEN`:
+
+```bash
+export CERC_NPM_AUTH_TOKEN=<your-token>
+```
+
+### Configure the hostname gitea.local
+
+How to do this depends on your operating system  but usually involves editing a `hosts` file. For example, on Linux add this line to the file `/etc/hosts` (needs sudo):
+
+```bash
+127.0.0.1       gitea.local
+```
+
+Test with:
+
+```bash
+ping gitea.local
+```
+
+```bash
+PING gitea.local (127.0.0.1) 56(84) bytes of data.
+64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.147 ms
+64 bytes from localhost (127.0.0.1): icmp_seq=2 ttl=64 time=0.033 ms
+```
+
+Although not necessary in order to build and publish packages, you can now access the Gitea web interface at: [http://gitea.local:3000](http://gitea.local:3000) using these credentials: `gitea_admin/admin1234` (Note: please properly secure Gitea if public internet access is allowed).
+
+### Build npm Packages
+
+Clone the required repositories:
+
+```bash
+laconic-so --stack fixturenet-laconicd setup-repositories
+```
+
+Build and publish the npm packages:
+
+```bash
+laconic-so --stack fixturenet-laconicd build-npms
+```
+
+Navigate to the Gitea console and switch to the `cerc-io` user then find the `Packages` tab to confirm that these two npm packages have been published:
+
+- `@cerc-io/laconic-registry-cli`
+- `@cerc-io/laconic-sdk`
+
+### Build and deploy fixturenet containers
+
+```bash
+laconic-so --stack fixturenet-laconicd build-containers
+laconic-so --stack fixturenet-laconicd deploy up
+```
+
+Check the logs:
+
+```bash
+laconic-so --stack fixturenet-laconicd deploy logs
+```
+
+### Test with the registry CLI
+
+```bash
+laconic-so --stack fixturenet-laconicd deploy exec cli "laconic cns status"
+```
+
+Try additional CLI commands, documented [here](https://github.com/cerc-io/laconic-registry-cli#operations).
diff --git a/docs/laconicd-fixturenet.md b/docs/laconicd-with-console.md
similarity index 100%
rename from docs/laconicd-fixturenet.md
rename to docs/laconicd-with-console.md
diff --git a/docs/spec.md b/docs/spec.md
index ad6ed3c9..1dc9ac62 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -1,7 +1,6 @@
 # Specification
 
-(note this page is out of date)
-
+Note: this page is out of date (but still useful) - it will no longer be useful once stacks are [decoupled from the tool functionality](https://github.com/cerc-io/stack-orchestrator/issues/315).
 
 ## Implementation