Skip to content
Snippets Groups Projects
Commit f083fb53 authored by Florian Sesser's avatar Florian Sesser
Browse files

Merge branch 'docs-expand'

parents 38eb4e75 dfb5d317
No related branches found
No related tags found
No related merge requests found
PrivateStorageio PrivateStorageio
================ ================
The backend for a private, secure, and end-to-end encrypted storage solution The backend for a private, secure, and end-to-end encrypted storage solution.
Building
--------
The build system uses `Nix`_ which must be installed before anything can be built.
Start by setting up the development/operations environment::
$ nix-shell
Documentation Documentation
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
There is documentation for:
* Users: ``docs/user/README.rst``
* Operators/Admins: ``docs/ops/README.rst``
* Developers: ``docs/dev/README.rst``
The documentation can be built using this command:: The documentation can be built using this command::
$ nix-build docs.nix $ nix-build docs.nix
The documentation is also built on and published by CI. The documentation is also built on and published by CI.
Testing
-------
The test system uses `Nix`_ which must be installed before any tests can be run.
Unit tests are run using this command::
$ nix-build nixos/unit-tests.nix
Unit tests are also run on CI.
The system tests are run using this command::
$ sudo --preserve-env nix-build nixos/system-tests.nix
The system tests boot QEMU VMs which prevents them from running on CI at this time.
Starting VMs require elevated privileges,
which is the reason for the suggested ``sudo`` command,
together with the ``--preserve-env`` option to avoid escaping the ``nix-shell`` set up at the top.
The build requires > 10 GB of disk space,
and the VMs might be timing out on slow or busy machines.
If you run into timeouts,
try `raising the number of retries <https://github.com/PrivateStorageio/PrivateStorageio/blob/e8233d2/nixos/modules/tests/run-introducer.py#L55-L62>`_.
It is also possible go through the testing script interactively - useful for debugging::
$ sudo --preserve-env nix-build -A private-storage.driver nixos/system-tests.nix
This will give you a result symlink in the current directory.
Inside that is bin/nixos-test-driver which gives you a kind of REPL for interacting with the VMs.
The kind of `Perl in this testScript <https://github.com/PrivateStorageio/PrivateStorageio/blob/78881a3/nixos/modules/tests/private-storage.nix#L180>`_ is what you can enter into this REPL.
Deployment
----------
See ``morph/README.rst``.
.. _Nix: https://nixos.org/nix
.. include::
../../README.rst
Architecture Overview
=====================
.. graphviz:: architecture-overview.dot
Developer documentation
=======================
Building
--------
The build system uses `Nix`_ which must be installed before anything can be built.
Start by setting up the development/operations environment::
$ nix-shell
Testing
-------
The test system uses `Nix`_ which must be installed before any tests can be run.
Unit tests are run using this command::
$ nix-build nixos/unit-tests.nix
Unit tests are also run on CI.
The system tests are run using this command::
$ sudo --preserve-env nix-build nixos/system-tests.nix
The system tests boot QEMU VMs which prevents them from running on CI at this time.
Starting VMs require elevated privileges,
which is the reason for the suggested ``sudo`` command,
together with the ``--preserve-env`` option to avoid escaping the ``nix-shell`` set up at the top.
The build requires > 10 GB of disk space,
and the VMs might be timing out on slow or busy machines.
If you run into timeouts,
try `raising the number of retries <https://github.com/PrivateStorageio/PrivateStorageio/blob/e8233d2/nixos/modules/tests/run-introducer.py#L55-L62>`_.
It is also possible go through the testing script interactively - useful for debugging::
$ sudo --preserve-env nix-build -A private-storage.driver nixos/system-tests.nix
This will give you a result symlink in the current directory.
Inside that is bin/nixos-test-driver which gives you a kind of REPL for interacting with the VMs.
The kind of `Perl in this testScript <https://github.com/PrivateStorageio/PrivateStorageio/blob/78881a3/nixos/modules/tests/private-storage.nix#L180>`_ is what you can enter into this REPL.
Architecture overview
---------------------
.. graphviz:: architecture-overview.dot
.. _Nix: https://nixos.org/nix
...@@ -6,13 +6,14 @@ ...@@ -6,13 +6,14 @@
Welcome to PrivateStorageio's documentation! Welcome to PrivateStorageio's documentation!
============================================ ============================================
Howdy! We separated the documentation into parts addressing different audiences. Please enjoy our docs for:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
:caption: Contents:
README Users <user/README>
architecture-overview Administrators <ops/README>
morph Developers <dev/README>
......
.. include::
../../morph/README.rst
Adminstrator documentation
==========================
This contains documentation regarding running PrivateStorageIo.
.. include::
../../../morph/README.rst
:start-line: 9
User documentation
==================
This will contain the user documentation for this project.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment