Commit 8bf0bf3e authored by Mathias Jud's avatar Mathias Jud

unified 'contributors guid' & 'users guide' in 'qaul.net manual'

parent 4c6f7f6b
Pipeline #1366 failed with stages
![](docs/banner.svg)
# qaul.net – قول
## Internet Independent Wireless Mesh Communication App
---
![http://qaul.net/](docs/qaul-net.png)
**qaul** is a decentralised networking project, aiming to create
easy-to-use solutions for ad-hoc wireless communication. It
supports many common desktop operating systems (Linux, Windows,
MacOS, BSD, …), and Android mobile phones. iOS support is on
the roadmap.
**qaul.net** is both a cross-platform application, implementing
**messaging**, **filesharing**, and **voice calls**, but also a
**development toolkit** to create fully decentralised third-party
applications.
a peer2peer wireless mesh communication app for **messaging**,
**filesharing**, and **voice calls**.
The project currently undergoes a complete rewrite in [Rust](https://rustlang.org).
In order to be able to run on unpriviledged mobile platforms qaul.net
implements **decentralised routing protocols** and utilities entirely
in userspace. The codebase is largely written in
[Rust](https://rustlang.org), with only a few compatibility components
being written in more platform specific languages. All parts of the
project are contained in this repository.
in userspace.
You are warmly invited to be part of this endeavour!
The old version 1.0 is in the independent [release-1.0.0](https://git.open-communication.net/qaul/qaul.net/-/tree/release-1.0.0) branch of this repository.
Following is an overview of the available components. Components have
additional information in their respective README files.
## Components
Components have additional information in their respective README files.
| Component | Description |
|-------------|------------------|
......@@ -48,19 +45,11 @@ additional information in their respective README files.
## Overview
Most traditional networking infrastructure (both the transmission
layer, as well as applications) operate in a centralised way.
Clients connect to servers, and devices to towers. This makes the
infrastructure vulnerable to attacks. Natural disasters or opressive
governments can easily shut down communication for millions of people,
potentially putting them at risk, and slowing down or disrupting any
organisation or activist movement.
qaul.net aims to solve this issue by creating decentralised circuits
between devices directly. These direct device-to-device connections can
between devices directly. These direct device-to-device connections can
be imperfect and unstable. qaul.net's routing approach takes these
issues into account by caching undelivered messages, and carrying them
towards their destination until the receipient comes back online.
towards their destination until the recepient comes back online.
Routing in a qaul.net network is done via a user's ed25519 public keys,
creating a 32 byte large address space. Connecting devices together happens
......@@ -69,33 +58,17 @@ when creating a circuit, roaming between different connection types is normal,
and no single technology has to work on all possible devices.
To learn more about the technical side of qaul.net, check out the
[contributor manual].
[qaul.net manual].
## How to use
There's no single way to use qaul.net. Various platforms support
different clients, and a qaul network can consist of many different
components interacting with each other. To get started, check out the
[user manual]!
[user manual]: https://docs.qaul.net/users
## Contributing
## qaul.net Manual
To join the development of qaul.net, read the qaul.net
Social processes, code, and design guidelines are outlined in the
[contributor manual]. We have a developer chat hosted on [Matrix]
where we would be happy to answer any questions you have. For more
long-form posting we have a [mailing list]. We also accept patches
via e-mail!
[contributor manual].
If you want some inspiration for what you can do with qaul.net, check
out the [services] section.
[qaul.net manual]: https://docs.qaul.net/manual
[contributor manual]: https://docs.qaul.net/contributors
[Matrix]: https://matrix.to/#/!ljaaylfsbkWFYNoNPT:fairydust.space?via=fairydust.space&via=matrix.org&via=public.cat
[mailing list]: https://lists.sr.ht/~qaul/community
[services]: ./services
## License
......@@ -103,6 +76,7 @@ qaul.net is free software licensed under the
[GNU Affero General Public License version 3](licenses/agpl-3.0.md) or
later.
**Additional Permissions:** For Submission to the Apple App Store:
Provided that you are otherwise in compliance with the AGPLv3 for each
......
......@@ -8,11 +8,10 @@ online under [https://docs.qaul.net](https://docs.qaul.net)**
## Guides
* `contributors`: the contributors' guide introduces and explains the
structure of qaul.net and should guide you through the steps of how
to the project.
* `manual`: the qaul.net manual introduces and explains the
structure of qaul.net and should guide you through the structure of
the project and shows you how to build it.
* `http-api`: contains the documentation of the qaul.net http-api.
* `index`: this folder contains the overview page.
## Build and Deploy
......
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="100%" height="100%" viewBox="0 0 600 100" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
<g id="Ebene1" transform="matrix(0.84858,0,0,1.11703,17.1251,-6.05572)">
<g transform="matrix(1,0,0,1,-10.8161,-0.0120401)">
<path d="M197.659,23.662C197.659,17.017 190.557,11.622 181.81,11.622L66.016,11.622C57.269,11.622 50.167,17.017 50.167,23.662L50.167,79.849C50.167,86.495 57.269,91.89 66.016,91.89L181.81,91.89C190.557,91.89 197.659,86.495 197.659,79.849L197.659,23.662Z" style="fill:rgb(0,14,115);"/>
</g>
<g transform="matrix(1.16516,0.511037,-0.661929,0.870961,1.36407,-53.1266)">
<path d="M137.073,-6.08L170.457,20.042L176.612,62.792L110.7,101.432L75.711,75.467L71.539,32.378L137.073,-6.08Z" style="fill:rgb(0,6,50);fill-opacity:0.78;"/>
</g>
<g transform="matrix(1.16429,0,0,1.587,-47.6446,-43.953)">
<path d="M138.12,34.951L201.374,47.609L201.374,72.925L138.12,85.583L74.866,72.925L74.866,47.609L138.12,34.951Z" style="fill:rgb(52,76,255);fill-opacity:0.42;"/>
</g>
<g transform="matrix(1.54535,0,0,0.977457,-58.074,-2.2451)">
<path d="M111.041,14.274L146.371,34.671L146.371,75.467L111.041,95.864L75.711,75.467L75.711,34.671L111.041,14.274Z" style="fill:rgb(52,76,255);fill-opacity:0.42;"/>
</g>
<g id="text835" transform="matrix(0.998535,0,0,0.758561,2.61521,13.0386)">
<path id="path859" d="M154.45,24.136L151.521,29.544L145.437,26.314L148.254,20.944L154.45,24.136ZM145.813,27.516L142.959,32.961L136.875,29.807L139.654,24.362L145.813,27.516ZM155.652,66.872L132.444,66.872L132.444,60.338L152.46,60.338C152.46,58.11 152.197,56.019 151.671,54.066C150.369,54.492 149.368,54.792 148.667,54.968C147.515,55.268 146.501,55.418 145.625,55.418C143.797,55.418 142.308,54.955 141.156,54.029C139.829,52.977 139.166,51.463 139.166,49.485C139.166,46.005 139.792,42.963 141.043,40.359C142.445,37.455 144.273,36.003 146.526,36.003C149.581,36.003 151.934,38.394 153.586,43.176C154.963,47.131 155.652,51.776 155.652,57.108L155.652,66.872ZM149.53,47.344C149.18,46.443 148.617,45.529 147.841,44.603C146.789,43.351 145.788,42.725 144.836,42.725C144.16,42.725 143.597,43.013 143.146,43.589C142.721,44.14 142.508,44.803 142.508,45.579C142.508,47.582 143.61,48.584 145.813,48.584C146.389,48.584 147.002,48.471 147.653,48.246C148.304,48.02 148.93,47.72 149.53,47.344L149.53,47.344Z" style="fill:rgb(142,154,234);fill-rule:nonzero;"/>
<path id="path861" d="M135.11,64.619C135.11,68.75 133.583,72.856 130.528,76.936C127.124,81.493 123.193,83.771 118.737,83.771C117.084,83.771 115.382,83.583 113.629,83.208C112.352,82.932 110.688,82.457 108.635,81.781C107.007,81.205 105.38,80.642 103.753,80.091L104.391,78.777C105.793,79.102 107.258,79.44 108.785,79.791C110.337,80.166 111.727,80.354 112.953,80.354C116.008,80.354 118.899,79.578 121.628,78.025C123.756,76.799 125.884,75.021 128.012,72.693C129.089,71.516 130.616,69.601 132.594,66.947C129.214,66.947 126.685,66.409 125.008,65.332C123.105,64.106 122.154,62.09 122.154,59.286C122.154,56.708 122.755,54.317 123.957,52.114C125.359,49.56 127.136,48.283 129.289,48.283C131.467,48.283 133.032,49.547 133.983,52.076C134.734,54.054 135.11,56.808 135.11,60.338L135.11,64.619ZM132.744,60.526C132.193,58.122 131.53,56.457 130.754,55.531C130.078,54.73 129.252,54.329 128.275,54.329C127.574,54.329 126.961,54.567 126.435,55.043C125.934,55.493 125.684,56.069 125.684,56.77C125.684,57.997 126.235,58.936 127.336,59.587C128.438,60.213 130.24,60.526 132.744,60.526Z" style="fill:rgb(142,154,234);fill-rule:nonzero;"/>
<path id="path863" d="M101.913,62.215C101.913,66.221 100.974,69.401 99.096,71.754C97.419,73.832 94.953,75.322 91.698,76.223C88.944,76.974 85.452,77.35 81.221,77.35C76.389,77.35 72.646,76.461 69.992,74.683C67.088,72.73 65.636,69.814 65.636,65.933C65.636,63.78 65.949,61.539 66.575,59.211C67.101,57.233 67.902,55.068 68.978,52.714C69.754,51.012 70.806,48.959 72.133,46.556L73.334,47.269C72.408,48.947 71.632,50.449 71.006,51.776C70.18,53.553 69.567,55.143 69.166,56.545C68.69,58.247 68.452,59.9 68.452,61.502C68.452,64.581 69.567,66.91 71.795,68.487C74.048,70.064 77.165,70.853 81.146,70.853C85.377,70.853 89.295,70.127 92.9,68.675C96.855,67.072 98.833,65.157 98.833,62.929C98.833,60.501 98.445,56.382 97.669,50.574C97.068,46.118 96.33,41.135 95.453,35.628L94.214,28.342L92.487,27.441C92.487,24.086 93.175,21.032 94.552,18.278L95.191,18.278C95.291,19.229 95.466,19.943 95.716,20.418C95.967,20.869 96.38,21.207 96.956,21.432C97.732,21.758 98.583,22.146 99.509,22.596C100.185,22.922 100.773,23.21 101.274,23.46C101.274,25.213 101.212,26.49 101.086,27.291C100.961,28.092 100.711,29.218 100.335,30.671L98.195,29.995C98.245,30.545 98.608,33.061 99.284,37.543C100.06,42.775 100.636,47.019 101.011,50.273C101.612,55.481 101.913,59.462 101.913,62.215Z" style="fill:rgb(142,154,234);fill-rule:nonzero;"/>
</g>
</g>
<g id="Layer-1" serif:id="Layer 1" transform="matrix(1,0,0,1,-44.2658,0.737764)">
<g id="text839">
<path id="path842" d="M253.669,70.758L265.915,70.758L262.757,67.089L262.757,40.251L258.875,41.19C257.339,40.849 256.144,40.678 254.053,40.678C246.288,40.678 242.789,46.481 242.789,51.985C242.789,57.105 245.52,62.011 251.109,62.011C253.797,62.011 256.101,60.091 257.637,57.702L257.637,67.089L253.669,70.758ZM257.637,56.294C256.784,56.934 255.973,57.318 254.437,57.318C250.81,57.318 247.866,54.758 247.866,48.102C247.866,45.542 248.634,42.171 252.389,42.171C254.608,42.171 256.357,43.409 257.637,44.774L257.637,56.294Z" style="fill:rgb(0,14,115);fill-rule:nonzero;"/>
<path id="path844" d="M278.87,61.585L287.19,61.585L284.033,58.811L283.99,58.811L283.99,44.347L284.929,40.678L267.35,40.678L267.35,47.505L267.648,47.505C269.825,44.262 271.873,41.873 275.286,41.873C278.785,41.873 278.87,44.518 278.87,47.931C271.489,50.534 266.326,52.753 266.326,57.105C266.326,60.561 268.502,62.011 271.446,62.011C274.262,62.011 277.249,59.579 278.87,58.001L278.87,61.585ZM278.87,56.849C277.803,57.958 276.481,58.641 275.158,58.641C273.366,58.641 271.958,57.745 271.958,55.697C271.958,53.649 272.171,51.814 278.87,49.126L278.87,56.849Z" style="fill:rgb(0,14,115);fill-rule:nonzero;"/>
<path id="path846" d="M296.543,40.635L288.223,40.635L291.423,44.347L291.423,55.185C291.423,59.195 293.471,62.011 297.823,62.011C300.852,62.011 302.815,60.561 304.351,58.427L304.351,61.841L312.372,61.585L309.471,58.086L309.471,40.635L301.193,40.635L304.351,44.347L304.351,57.105C303.241,58.385 301.748,59.11 300.297,59.11C297.012,59.11 296.543,57.019 296.543,53.734L296.543,40.635Z" style="fill:rgb(0,14,115);fill-rule:nonzero;"/>
<path id="path848" d="M317.27,57.915L314.113,61.585L325.547,61.585L322.39,57.915L322.39,31.291L314.369,33.723L317.27,37.008L317.27,38.63L314.369,39.526L317.27,42.811L317.27,57.915Z" style="fill:rgb(0,14,115);fill-rule:nonzero;"/>
<path id="path850" d="M326.639,58.769L330.309,62.694L333.935,58.769L330.309,54.801L326.639,58.769Z" style="fill:rgb(0,14,115);fill-rule:nonzero;"/>
<path id="path852" d="M360.075,61.585L356.832,57.915L356.832,46.993C356.832,42.982 354.784,40.166 350.432,40.166C347.872,40.166 345.099,41.489 343.392,44.134L343.392,40.251L335.371,43.11L338.272,46.395L338.272,57.915L335.029,61.585L346.464,61.585L343.392,57.915L343.392,45.585C344.757,43.75 346.379,43.067 347.957,43.067C351.243,43.067 351.712,45.158 351.712,48.443L351.712,57.915L348.64,61.585L360.075,61.585Z" style="fill:rgb(0,14,115);fill-rule:nonzero;"/>
<path id="path854" d="M380.595,49.51L380.638,49.51L380.595,49.424C380.553,43.664 377.438,40.251 372.361,40.251C365.406,40.251 361.993,46.566 361.993,52.07C361.993,57.19 365.15,62.182 370.739,62.182C375.817,62.182 378.846,58.257 380.382,54.374L379.742,54.118C379.102,55.91 376.542,57.361 373.641,57.361C370.313,57.361 367.369,55.057 366.899,49.553L380.595,49.553L380.595,49.51ZM375.091,48.273L366.814,48.273L366.814,47.974C366.814,45.414 368.137,41.531 371.379,41.531C373.257,41.531 375.091,43.323 375.091,47.889L375.091,48.273Z" style="fill:rgb(0,14,115);fill-rule:nonzero;"/>
<path id="path856" d="M390.289,34.619L382.353,40.678L385.169,43.366L385.169,55.526C385.169,60.39 387.686,62.097 390.63,62.097C394.086,62.097 396.39,60.347 398.438,56.891L397.926,56.209C396.987,58.043 395.025,58.683 393.745,58.683C391.227,58.683 390.289,57.574 390.289,53.478L390.289,42.982L397.542,42.982L398.481,40.678L390.289,40.678L390.289,34.619Z" style="fill:rgb(0,14,115);fill-rule:nonzero;"/>
</g>
</g>
</svg>
This diff is collapsed.
#!/bin/sh
# create book
./build.sh
# upload book to web server
rsync -azzhe "ssh -p 2222" ./book/ admin@docs.qaul.net:/home/admin/contributors
# Design Guide
\ No newline at end of file
#!/bin/sh
# build and upload the contributors manual
cd contributors
# build and upload the qaul.net manual
cd manual
./deploy.sh
cd ..
......@@ -10,11 +10,6 @@ cd http-api
./deploy.sh
cd ..
# build and upload the users manual
cd users/
./deploy.sh
cd ..
# build and upload the rust documentation
cd ..
cargo doc --no-deps
......
[book]
authors = ["Katharina Fey", "Mathias Jud", "Jess 3Jane"]
authors = ["qaul.net community"]
multilingual = false
src = "src"
title = "qaul.net Contributors Manual"
title = "qaul.net Manual"
[build]
create-missing = false
[output.html]
preferred-dark-theme = "navy"
git-repository-url = "https://git.open-communication.net/qaul/qaul.net/-/tree/master/docs%2Fcontributors"
git-repository-url = "https://git.open-communication.net/qaul/qaul.net/-/tree/master/docs%2Fmanual"
git-repository-icon = "fa-git"
......@@ -4,4 +4,4 @@
./build.sh
# upload book to web server
rsync -azzhe "ssh -p 2222" ./book/ admin@docs.qaul.net:/home/admin/users
rsync -azzhe "ssh -p 2222" ./book/ admin@docs.qaul.net:/home/admin/manual
......@@ -5,8 +5,12 @@
- [Social](./social/_intro.md)
- [Contributions](./social/contributions.md)
- [Code of Conduct](./social/code-of-conduct.md)
- [Manuals & websites](./manuals/_intro.md)
- [Technical](./technical/index.md)
- [Documentation & Website](./manuals/_intro.md)
- [Build qaul.net](./build/_intro.md)
- [Clients](./clients/_intro.md)
- [Linux Client](./clients/qaul-linux.md)
- [qaul-hubd Daemon](./clients/qaul-hubd.md)
- [Technical](./technical/_intro.md)
- [qaul.net Services](./technical/services.md)
- [RPC layer](./technical/rpc-layer/index.md)
- [qrpc-sdk](./technical/rpc-layer/sdk.md)
......@@ -27,12 +31,11 @@
- [Testing](./test/index.md)
- [linux-http-test](./test/linux-http-test.md)
- [Translations](./translations/_intro.md)
- [Design Guides](./design/_intro.md)
- [qaul.net website](./website/_intro.md)
- [How to Create a Tutorial](./website/tutorials.md)
- [Translate the Web Site](./website/translate.md)
- [qaul.net Website](./website/_intro.md)
- [How to Create a Tutorial](./website/tutorials.md)
- [Translate the Web Site](./website/translate.md)
- [Licenses](./legal/README.md)
- [GNU Affero General Public License version 3 or later](./legal/agpl-3.0.md)
- [Creative Commons Attribution 4.0 International License](./legal/cc-by.md)
- [Mozilla Public License version 2.0](./legal/mpl-v2.0.md)
- [GNU GENERAL PUBLIC LICENSE](./legal/gpl-3.0.md)
- [GNU Affero General Public License version 3 or later](./legal/agpl-3.0.md)
- [Creative Commons Attribution 4.0 International License](./legal/cc-by.md)
- [Mozilla Public License version 2.0](./legal/mpl-v2.0.md)
- [GNU GENERAL PUBLIC LICENSE](./legal/gpl-3.0.md)
......@@ -7,8 +7,9 @@ build, and configure them.
| Client name | Desktop platforms | Mobile platform | Version |
|-------------|-------------------|-----------------|---------|
| [qaul-linux] | Linux | | 0.1.0 |
| [qaul-hubd] | Linux, MacOS | - | 0.1.0 |
| [qauldroid] | - | Android | 0.1.0 |
[qaul-hubd]: ./qaul-hubd/_intro.md
[qauldroid]: ./qauldroid/_intro.md
[qaul-linux]: ./qaul-linux.md
[qaul-hubd]: ./qaul-hubd.md
# Configuration
# qaul-hubd Daemon
This is a multi purpose router and database daemon for qaul.net. It
handles network driver and user state as a detached process, and
allows both http and unix ipc clients to connect to it.
It doesn't come with it's own user interface, which means you will
have to build one separately and configure it to connect to your
`qaul-hubd` instance.
Because all networking is done in userspace, no root access is
required.
## Configuration
In order for `qaul-hubd` to work properly it will have to run in the
background to handle incoming and outgoing network connections. It's
......
# qaul-linux - qaul.net linux client
This client is still in it's early stage. It provides the
This client is still in it's early stage.
## Build & Run
......@@ -53,5 +53,4 @@ In order for the qaul.net instance to connect to an Internet overlay network. Yo
```
144.91.74.192:9001
95.216.98.55:11443
```
# qaul.net contributors manual
# qaul.net Manual
Welcome to the contributors manual. The purpose of this document is
Welcome to the qaul.net manual. The purpose of this document is
to explain qaul.net internal concepts, structures, and protocols.
It's source code can be [found][repo] in the main qaul.net code repo.
If you find any issues with it (typos, outdated sections, unclear
sections), [open an MR], or [send us a patch]!
[repo]: https://git.open-communication.net/qaul/qaul.net/tree/master/docs/contributors
[repo]: https://git.open-communication.net/qaul/qaul.net/tree/master/docs/manual
[open an MR]: social/contributions.html#submitting-a-pr
[send us a patch]: social/contributions.html#submitting-an-e-mail-patch
# qaul.net documentation
This section outlines various pieces of the qaul.net project that
aren't directly code related.
## Manuals
Because this manual is part of the main source repository, you can
build it from the same environment as the main code. If you use [nix]
to scope dependencies, you can simply run `mdbook serve` to build and
serve the built html files.
```console
$ cd docs/contributors
$ mdbook serve
```
If you have access to the qaul.net servers, you can run `./deploy.sh`
at any level to recursively deploy sections to production.
## Websites
qaul.net runs many different web services:
* [qaul.net](https://qaul.net) the qaul.net web site
* [contributor manual](https://docs.qaul.net/contributors) (this document)
* [user manual](https://docs.qaul.net/users)
* [qaul.net manual](https://docs.qaul.net/manual) (this document)
* [http-api](https://docs.qaul.net/http-api) qaul.net REST API guide
* [Rust documentaiion](https://docs.qaul.net/api) the qaul.net rust software API documentation (automatically created from the qaul.net code sources)
* [Rust documentation](https://docs.qaul.net/api) the qaul.net rust software API documentation (automatically created from the qaul.net code sources)
* [get.qaul.net](https://get.qaul.net) the qaul.net download directory for the qaul.net binaries and big content files (e.g. videos, etc.).
This chapter explains how they are hosted, updated, where to look to
......@@ -38,8 +14,7 @@ working or you would like to have access to it.
### qaul.net Web Site
There is an [own chapter] in this guide on the editing of the qaul.net
web site. Please have a look there on how to edit and translate the
The chapter [website] in this guide explains how to edit and translate the
web site.
* Server: https://qaul.net
......@@ -47,7 +22,7 @@ web site.
* Updated: by deploy script
* Admin contact: contact@qaul.net
[own chapter]: /website
[website]: /website
### docs.qaul.net Documentation
......
......@@ -6,30 +6,18 @@ make engaging with us as easy as possible!
## Communication
The qaul.net projet uses [matrix] as development and social chat. Feel
free to drop by!
Our [community mailing list] is for long-form discussion and work log
updates. You can post questions there, show off your projects using
`libqaul` or submit patches! The mailing list usually is mixed volume.
We also have an [announcement mailing list], which is very low volume,
where you will get informed about new versions and releases of the
qaul.net software and occasional project related news.
We have an open weekly developer voice chat meeting. We are meeting
Mondays, at 17:00 UTC on the online platform [jitsi]. The meetings
are announced on the community mailing list, where you can find the
records of the meetings as well. They are open and free to join for
Mondays, at 17:00 UTC on the online platform [jitsi].
They are open and free to join for
everyone, feel free to drop in. *Note: weekly voice chat's have been
paused for the time being*
[matrix]: https://matrix.to/#/!ljaaylfsbkWFYNoNPT:matrix.org
[announcement mailing list]: https://lists.sr.ht/~qaul/announcements
[community mailing list]: https://lists.sr.ht/~qaul/community
[jitsi]: https://meet.jit.si/qaul.net
Or contact us directly via email: contact@qaul.net
## Code of Conduct
**TLDR:** be nice!
......
......@@ -2,11 +2,11 @@
First of all: thank you for wanting to help out :)
Day-to-day development of qaul.net happens on [our own gitlab
Day-to-day development of qaul.net happens on [open-communication's gitlab
instance](https://git.open-communication.net/qaul).
## Submitting an MR
## Submitting a Merge Request
- If a relevant issue exists, please tag in your description, not the
title.
......@@ -16,20 +16,3 @@ instance](https://git.open-communication.net/qaul).
- Feel free to open a work-in-progress MR as a place to have a
discussion about changes or to get feedback.
## Submitting an e-mail patch
If you can't contribute via gitlab (for whatever reason),
you're very welcome to submit your patch via e-mail.
The easiest way of doing this is to configure `git send-email`.
Patches should be submitted to the community mailing list at
[~qaul/community@lists.sr.ht](mailto:~qaul/community@lists.sr.ht)
**Manually**
- Send an e-mail with the title `[PATCH]: <your title here>`.
- Format your patch with `git diff -p`
- Don't send HTML e-mail!
- Make sure your line-wrapping is wide enough to allow the patch to
stay un-wrapped!
# Technical Documentation
This is an introductory chapter into the technical layers of qaul.net!
It is aimed at two different types of people:
1. People wanting to contribute to the qaul.net core
2. People wanting to write apps for a qaul network
Before getting started, we need to cover a few basics in project
structure. Each section in this document has it's own sub-chapter
that will go into more details.
This is an introductory chapter into the technical layers of qaul.net.
## Introduction
......@@ -27,7 +19,7 @@ that are exchanged. The API of this library is called the "libqaul
service API" in other parts of the docs. An application written to
use `libqaul` is called a "service".
A service provicdes more specific functionality. Not all services are
A service provides more specific functionality. Not all services are
user-facing. For example, a service can provide an easy interface to
send rich-payload messages, that operates on a higher level than the
libqaul service API. Other services can then depend on this
......
[book]
authors = ["The qaul.net developers"]
language = "en"
multilingual = false
src = "src"
title = "qaul.net users manual"
#!/bin/sh
# crate the structural dependencies SVG image
dot -Tsvg src/assets/dependencies.dot -o src/assets/dependencies.svg
# build this mdbook
mdbook build
# Summary
- [Available clients](./clients.md)
- [Nix builds](./nix.md)
- [Building this manual](./manual.md)
- [qaul-hubd](./qaul-hubd/_intro.md)
- [Manual build](./qaul-hubd/build.md)
- [Configuration](./qaul-hubd/config.md)
- [qaul-emberweb](./webgui/_intro.md)
- [Manual build](./webgui/build.md)
# Building this manual
This manual is part of the main source repository and you can build it
from the same [nix](./nix.md) environment as the rest of the project.
```console
$ cd docs/users
$ mdbook build
```
If you want to enable live-reloading to work on this manual, you can
also use the dev server.
```console
$ mdbook serve
```
# Nix builds
While it is possible to install dependencies with platform specific
tools (such as `apt` on Debian, etc), it is far more recommended to
use [nix](https://nixos.org) to build qaul.net instead.
While the actual build isn't handled by nix (yet), it makes aquiring
the dependencies a lot easier. Follow the instructions on how to
install nix on your platform [here][nix-instructions]
[nix-instructions]: https://nixos.org/download.html
## Fetch dependencies
The `shell.nix` in the qaul.net repo root defines dependencies. Fetch
them into your environment by running `nix-shell` in the repo root
(this might take a while).
Afterwards you can simple run `cargo build --bin qaul-hubd --release`
to build a new hubd binary.
The output artefact will be written to `./target/release/qaul-hubd`.
## Lorri & direnv
You can enable automatic environment loading when you enter the
qaul.net repository, by configuring [lorri] and [direnv] on your system.
[lorri]: https://github.com/target/lorri
[direnv]: https://direnv.net/
```console
❤ (uwu) ~/p/code> cd qaul.net
direnv: loading ~/projects/code/qaul.net/.envrc
direnv: export +AR +AR_FOR_TARGET +AS +AS_FOR_TARGET +CC
// ... snip ...
❤ (uwu) ~/p/c/qaul.net> cargo build lorri-keep-env-hack-qaul
...
```
# qaul-hubd
This is a multi purpose router and database daemon for qaul.net. It
handles network driver and user state as a detached process, and
allows both http and unix ipc clients to connect to it.
It doesn't come with it's own user interface, which means you will
have to build one separately and configure it to connect to your
`qaul-hubd` instance.
Because all networking is done in userspace, no root access is
required.
# Manual build
Building `qaul-hubd` with [nix](../nix.md) is recommended! If you
need to build via system dependencies, follow this guide, depending on
your platform.
## Install dependencies
**Rust**
You will need to have a Rust compiler, and cargo toolchain installed
on your system (minimum version `v1.42`). [Install instructions][rust]
[rust]: https://www.rust-lang.org/tools/install
**Homebrew**
On MacOS you will need to install a package manager first to install
all the developer tools. Alternatively you can also get them by
downloading XCode from the App Store.
[Homebrew](https://brew.sh/) is a popular package manager for MacOS!
**Build Tools**
You need to install a general development environment with the
following tools available.
* Debian/ Ubuntu/ Mint: `sudo apt install make gcc cmake git`
* Fedora/ CentOS: `sudo dnf install make gcc cmake git`
* Arch Linux: `sudo pacman -Sy make gcc cmake git`
* MacOS: `brew install make gcc cmake git`
## Build from source
Clone the main code repo:
```console
$ git clone https://git.open-communication.net/qaul/qaul.net
$ cd qaul.net/
```
Then simply run `cargo build --bin qaul-hubd --release` to build the
hubd binary.
The output artefact will be written to `./target/release/qaul-hubd`.
# qaul-emberweb
This is a web client written in ember.js. It's meant to be installed
on a communal computer and can provide multiple users access to an
underlying qaul.net instance.
Requires a running `qaul-hubd` instance to connect to.
......@@ -3,7 +3,7 @@
The **web GUI** is the **HTML5 GUI** for qaul.net, which is
qaul.net's default GUI.
For how to develop, build and test the web GUI [read the chapter in the contributors' guide](https://docs.qaul.net/contributors/technical/webgui/_intro.html).
For how to develop, build and test the web GUI [read the chapter in the manual](https://docs.qaul.net/manual/technical/webgui/_intro.html).
## Prequisites
......@@ -39,5 +39,5 @@ Now you can open the WebGUI in your web browser: http://localhost:4200/
## Documentation
More documentation you'll find in the contributors guide.
[read the chapter in the contributors' guide](https://docs.qaul.net/contributors/technical/webgui/_intro.html).
More documentation you'll find in the qaul.net manual.
[read the chapter in the qaul.net manual](https://docs.qaul.net/manual/technical/webgui/_intro.html).
......@@ -62,10 +62,10 @@ impl<K: StreamResponder + Send + Sync + 'static> Responder<K> {
// basically the same thing, and the switching logic stays in one
// place. If you need some context as to why this is required,
// what it does, and how it actually works, there's an RPC chapter
// in the contributors guide for you to read up on these things.
// in the qaul.net manual for you to read up on these things.
// If you have more questions afterwards, feel free to reach out
// to us. When touching this function, try to leave comments for
// anything that's not immediatly obvious. Also: =^-^=!
// anything that's not immediately obvious. Also: =^-^=!
pub async fn respond(&self, req: Request) -> Response {
// TODO: currently the ids all map into Response::UserId which is wrong
match req {
......
......@@ -14,11 +14,11 @@
//! 2. Identities don't change mid-route
//!
//! This crate is part of the qaul.net project. The docs for this
//! crate are propably lacking because currently Ratman/ libqaul are
//! crate are probably lacking because currently Ratman/ libqaul are
//! the only users of it. If you have questions, don't hesitate to