Merge pull request #16 from atsign-foundation/gitbook

docs(automated): Update docs from Gitbook
atsign-foundation · Mar 18, 2024 · 24a2440 · 24a2440
2 parents c1522c0 + 9fc2128
commit 24a2440
Show file tree

Hide file tree

Showing 23 changed files with 402 additions and 13 deletions.
diff --git a/docs/.gitbook/assets/API.png b/docs/.gitbook/assets/API.png
diff --git a/docs/.gitbook/assets/atDirectory (1).png b/docs/.gitbook/assets/atDirectory (1).png
diff --git a/docs/.gitbook/assets/atDirectory-dark (1).png b/docs/.gitbook/assets/atDirectory-dark (1).png
diff --git a/docs/.gitbook/assets/atDirectory-dark (2).png b/docs/.gitbook/assets/atDirectory-dark (2).png
diff --git a/docs/.gitbook/assets/atDirectory-dark.png b/docs/.gitbook/assets/atDirectory-dark.png
diff --git a/docs/.gitbook/assets/atDirectory.png b/docs/.gitbook/assets/atDirectory.png
diff --git a/docs/.gitbook/assets/atServer-dark.png b/docs/.gitbook/assets/atServer-dark.png
diff --git a/docs/.gitbook/assets/atServer.png b/docs/.gitbook/assets/atServer.png
diff --git a/docs/.gitbook/assets/at_talk.png b/docs/.gitbook/assets/at_talk.png
diff --git a/docs/.gitbook/assets/colin.png b/docs/.gitbook/assets/colin.png
diff --git a/docs/README.md b/docs/README.md
@@ -25,4 +25,4 @@ Some great places to start learning more about the technology
 
 Alternatively, learn how to work directly with our tech through some of our tutorials
 
-<table data-card-size="large" data-column-title-hidden data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Getting started with atSDK with Dart</td><td><a href="examples/atsdk-tutorial/using-the-atsdk-with-dart.md">using-the-atsdk-with-dart.md</a></td></tr></tbody></table>
+<table data-card-size="large" data-column-title-hidden data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Getting started with atSDK with Dart</td><td><a href="tutorials/atsdk-tutorial/using-the-atsdk-with-dart.md">using-the-atsdk-with-dart.md</a></td></tr></tbody></table>
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -11,17 +11,19 @@
   * [Events](learn/sdk/events.md)
   * [Synchronization](learn/sdk/synchronization.md)
 * [atProtocol](atprotocol.md)
+* [Infrastructure](infrastructure.md)
 
-## 🗒 Tutorials <a href="#examples" id="examples"></a>
+## 🗒️ Tutorials
 
-* [atSDK tutorial](examples/atsdk-tutorial/README.md)
-  * [Using the atSDK with Dart](examples/atsdk-tutorial/using-the-atsdk-with-dart.md)
-  * [Get sample code](examples/atsdk-tutorial/get-sample-code.md)
-  * [Cutting your atSigns keys](examples/atsdk-tutorial/cutting-your-keys.md)
-  * [Put and Get data asynchronously](examples/atsdk-tutorial/put-and-get-data-asynchronously.md)
-  * [Send and Receive data synchronously.](examples/atsdk-tutorial/send-and-receive-data-synchronously.md)
-  * [Remote Procedure Calls (RPC)](examples/atsdk-tutorial/rpc.md)
-  * [atTalk - Encrypted chat client](examples/atsdk-tutorial/attalk.md)
+* [atSDK tutorial](tutorials/atsdk-tutorial/README.md)
+  * [Using the atSDK with Dart](tutorials/atsdk-tutorial/using-the-atsdk-with-dart.md)
+  * [Get sample code](tutorials/atsdk-tutorial/get-sample-code.md)
+  * [Cutting your atSigns keys](tutorials/atsdk-tutorial/cutting-your-atsigns-keys.md)
+  * [Put and Get data asynchronously](tutorials/atsdk-tutorial/put-and-get-data-asynchronously.md)
+  * [Send and Receive data synchronously.](tutorials/atsdk-tutorial/send-and-receive-data-synchronously.md)
+  * [Remote Procedure Calls (RPC)](tutorials/atsdk-tutorial/rpc.md)
+  * [atTalk - Encrypted chat client](tutorials/atsdk-tutorial/attalk.md)
+* [Flutter & atSDK app](tutorials/flutter-and-atsdk-app.md)
 
 ***
 

diff --git a/docs/examples/atsdk-tutorial/attalk.md b/docs/examples/atsdk-tutorial/attalk.md
diff --git a/docs/infrastructure.md b/docs/infrastructure.md
@@ -0,0 +1,41 @@
+---
+description: How we scale and provide resilience.
+---
+
+# Infrastructure
+
+The atPlatform is designed to be distributed and allows people to run their own infrastructure for atDirectory and atServer services on their own networks. Here, we show how at a high level how Atsign runs the Internet atPlatform Infrastructure.
+
+Atsign services are monitored by an independent third party for uptime and can be seen here:
+
+{% embed url="https://status.atsign.com/" %}
+UpTimeRobot Reports
+{% endembed %}
+
+## atDirectory
+
+Atsign runs the Internet atDirectory, which has to be resilient and dependable. To provide that level of service, we use Google's Cloud Platform, Kubernetes, containers, and a distributed in-memory database.&#x20;
+
+<figure><picture><source srcset=".gitbook/assets/atDirectory-dark (1).png" media="(prefers-color-scheme: dark)"><img src=".gitbook/assets/atDirectory (1).png" alt="Architecture Diagram of the atDirectory infrastructure"></picture><figcaption><p>Highly available design</p></figcaption></figure>
+
+The atDirectory runs in a GCP Virtual Private Cloud. This VPC also houses an auto-scaling Kubernetes cluster which is spread across multiple datacenters and availability zones.
+
+The atDirectory service is found on the well-known DNS address `root.atsign.org` on port `64.` This is load balanced across the atDirectory containers. These containers, through an internal load balancer, to read-only in-memory databases containing the atSign to Fully Qualified Domain Name (FQDN) and port number mappings for all atSigns.
+
+The read-only databases are kept up to date with a single read-write database. This database is updated by the registrar [website](https://my.atsign.com/), which is run in another Kubernetes cluster.
+
+This design has proved to be reliable and allows upgrades in place without downtime. It automatically scales as load increases by spinning up more containers, and, if required, by adding new machines to the cluster itself. GCP's platform and Kubernetes have demonstrated resilience during data center or hardware issues, and have self-healed the infrastructure.
+
+## atServers
+
+Each atSign has its own dedicated personal data store, called an "atServer," running as a Docker container within a Docker Swarm. Atsign runs a number of Docker Swarms and can move atServers from one swarm to another. However, for high availability, Atsign relies on the Docker Swarm's manager nodes to orchestrate and ensure each atServer is up and running even if hardware fails within a swarm.
+
+Why Docker Swarm and not Kubernetes? Kubernetes is an excellent choice for groups of containers that provide a service like the atDirectory or websites. But, Kubernetes does not scale down well for thousands or millions of tiny independent containers like atServers.  Docker Swarm also provides highly resilient networking and is very lightweight.
+
+<figure><picture><source srcset=".gitbook/assets/atServer-dark.png" media="(prefers-color-scheme: dark)"><img src=".gitbook/assets/atServer.png" alt=""></picture><figcaption><p>resilient atServer Cluster</p></figcaption></figure>
+
+The FQDN and port number for a given atSign from the atDirectory is connected to the Docker Swarm. Each Docker Swarm node will route the port number to the right container on the swarm via its internal VXLAN. The Manager Nodes are responsible for ensuring each container is running and available across the whole swarm.
+
+For data requiring persistent storage beyond the Docker Swarm, encrypted atServer data gets transferred to a highly resilient NetApp Cloud Volume managed by GCP. This cloud volume functions as a network file system accessible to the atServers. &#x20;
+
+All infrastructure components are distributed across multiple data centers and availability zones, and have proven to be highly reliable with very little downtime of individual atServers during failures or upgrades.
diff --git a/docs/examples/atsdk-tutorial/README.md → docs/tutorials/atsdk-tutorial/README.md b/docs/examples/atsdk-tutorial/README.md → docs/tutorials/atsdk-tutorial/README.md
diff --git a/docs/tutorials/atsdk-tutorial/attalk.md b/docs/tutorials/atsdk-tutorial/attalk.md
@@ -0,0 +1,77 @@
+---
+description: Let's chat!
+---
+
+# atTalk - Encrypted chat client
+
+For the final example we have at\_talk, which is a fully end-to-end encrypted chat application in less than 300 lines of code. There is nothing pretty, its just a command line app, that takes the Unix/Linux command `talk` to a global level.
+
+The command `talk` allows people on a Unix/Linux machine to IM each other, at\_talk allows anyone with an atSign to talk with each other.
+
+This code is in a separate repo so once again in VS Code click the "Clone Git Repository" button. The enter:
+
+```
+https://github.com/atsign-foundation/at_talk.git
+```
+
+<figure><img src="../../.gitbook/assets/VScode Git.png" alt=""><figcaption></figcaption></figure>
+
+Like before, you will get asked if you want to run `pub get` and say yes or if you prefer you can open a terminal window and type:
+
+```
+ dart pub get
+```
+
+This as we know pulls in the needed libraries and the code will loose all the red underlines as those libraries are loaded.
+
+At this point we can open two terminal panels as we have done before and run the at\_talk code.  You can run at\_talk without any arguments and it will return some help:
+
+```
+dart run .\bin\at_talk.dart
+-k, --key-file                Your atSign's atKeys file if not in ~/.atsign/keys/
+-a, --atsign (mandatory)      Your atSign
+-t, --toatsign (mandatory)    Talk to this atSign
+-d, --root-domain             Root Domain (defaults to root.atsign.org)
+-n, --namespace               Namespace (defaults to ai6bh)
+-v, --verbose                 More logging
+    --never-sync              Completely disable sync
+Invalid argument(s): Option atsign is mandatory.
+```
+
+&#x20;From here you can split windows like before and run two at\_talk applications and send messages to each other.
+
+In the left window for example (subsitute your own atSigns!
+
+```
+ dart run .\bin\at_talk.dart -a "@7capricorn" -t "@energetic22" -n "atsign"
+```
+
+In the right window, the same but in reverse.
+
+```
+ dart run .\bin\at_talk.dart -a "@energetic22" -t "@7capricorn" -n "atsign"
+```
+
+In this session you can see the typed messages in white and th received messages in green with the prompts in red.&#x20;
+
+<figure><img src="../../.gitbook/assets/at_talk.png" alt=""><figcaption><p>talking atSigns</p></figcaption></figure>
+
+Unlike Linux talk, however these two atSigns can be anywhere on the Internet and communicating with Privacy, get a friend to run through the demo and use at\_talk !
+
+There are a couple of features, that are worth mentioning you can use the `/` and then an atSign to change who you are sending messages to and yes you can message to yourself.
+
+The other feature that has proved very useful is being able to "pipe" commands to at\_talk. To do this you can compile the code to a binary using:
+
+```
+dart compile exe -o attalk bin/at_talk.dart
+```
+
+Now you can "pipe" the output of a command into the chat with the other atSign.
+
+```
+cat .\bin\at_talk.dart| attalk -a "@energetic22" -t "@7capricorn" -n "atsign"
+```
+
+This prints the code of at\_talk.dart into the receiving atsigns chat window. To our knowledge the is the only chat application that you can pipe things too!
+
+If you go this far first thank you and second, please enjoy your continuing journey and raise issues and PR's to any of the repos!
diff --git a/docs/tutorials/atsdk-tutorial/cutting-your-atsigns-keys.md b/docs/tutorials/atsdk-tutorial/cutting-your-atsigns-keys.md
@@ -0,0 +1,25 @@
+---
+description: It takes two to tango!
+---
+
+# Cutting your atSigns keys
+
+To run through the tutorial you will need at least two atSigns, so you can send and receive. You can get your atSigns for free at [atsign.com](https://atsign.com/) or if you like purchase some that are more personal to you.&#x20;
+
+Once you have you atsigns you are ready to activate them, which means spinning up your atServer per atSign and cutting your cryptographic keys for each atSign. Sounds complicated but it is easy ! In fact just a single command. In the terminal window type:
+
+```
+dart run .\bin\at_activate.dart 
+```
+
+You will get an error message telling you to add the `-a` flag and your atsign, so if you atSign was @crunchfrog you would type:
+
+```
+dart run .\bin\at_activate.dart -a "@crunchyfrog"
+```
+
+\*Note on windows the atSign needs to be in double quotes so the shell does not get confused with the @ symbol. Below you can see the activation process for two atSigns @energetic22 and @7capricon. Once the command is run you will get and email with the one time password, enter that and the program will create an atKeys file for that atSign. Any atKeys files you create will be located in your home directory then .atsign/keys.
+
+These keys are important to be kept safe, as they are the only keys to your atSign and your data. Talking of data lets send some between the two atSigns next.
+
+<figure><img src="../../.gitbook/assets/image (19).png" alt=""><figcaption></figcaption></figure>
diff --git a/...xamples/atsdk-tutorial/get-sample-code.md → ...torials/atsdk-tutorial/get-sample-code.md b/...xamples/atsdk-tutorial/get-sample-code.md → ...torials/atsdk-tutorial/get-sample-code.md
diff --git a/...torial/put-and-get-data-asynchronously.md → ...torial/put-and-get-data-asynchronously.md b/...torial/put-and-get-data-asynchronously.md → ...torial/put-and-get-data-asynchronously.md
diff --git a/docs/examples/atsdk-tutorial/rpc.md → docs/tutorials/atsdk-tutorial/rpc.md b/docs/examples/atsdk-tutorial/rpc.md → docs/tutorials/atsdk-tutorial/rpc.md
diff --git a/...al/send-and-receive-data-synchronously.md → ...al/send-and-receive-data-synchronously.md b/...al/send-and-receive-data-synchronously.md → ...al/send-and-receive-data-synchronously.md
@@ -1,5 +1,5 @@
 ---
-description: Let's talk
+description: Send me a txt!
 ---
 
 # Send and Receive data synchronously.

diff --git a/...sdk-tutorial/using-the-atsdk-with-dart.md → ...sdk-tutorial/using-the-atsdk-with-dart.md b/...sdk-tutorial/using-the-atsdk-with-dart.md → ...sdk-tutorial/using-the-atsdk-with-dart.md