Merge pull request #13 from orchestracities/fix-build

Migrate to Nix

README.md

@@ -1,36 +1,91 @@
-# Orchestra Cities 
-
-[![Documentation badge](https://img.shields.io/readthedocs/orchestracities.svg)](https://docs.orchestracities.io/en/latest/)
+# Orchestra Cities
 
 ![OC Logo](docs/rsrc/OC_Logo_color-300x190.jpg)
 
 **Orchestra Cities** is a data and IoT-driven solution that allows cities to
 collaboratively develop and share Smart City Services using Open APIs and
 Open Standards. Launched in 2018 by [Martel Innovate](https://www.martel-innovate.com),
 Orchestra Cities was initially developed and tested with Antwerp and Helsinki
-as solution for the [Select4Cities](https://www.select4cities.eu/)
+as a solution for the [Select4Cities](https://www.select4cities.eu/)
 Pre-Commercial Procurement (PCP). Following the PCP, Martel further invested
 on the platform for the benefit of its customers.
 
-## Documentation
 
-This repository hosts the main documentation of Orchestra Cities.
+### Repository content
+
+This repository hosts the source and build tools for Orchestra Cities'
+documentation site.
+
+The documentation consists of an introduction, where the most important
+topics and ideas are briefly explained, and a tutorial, where the user
+can get some hands-on experience of the most important platform features.
+
+The documentation site source is in the `docs` folder and it gets fed
+into MkDocs to build a static site. Nix provides reproducible, sand-boxed
+and cross-platform development environments.
+
+
+### Development environment
+
+We use Nix to get proper, isolated and reproducible development
+environments. This is a sort of virtual shell environment on steroids
+which has in it all the tools you need with the right versions. Plus,
+it doesn't pollute your machine with libraries that could break your
+existing programs—everything gets installed in an isolated Nix store
+directory and made available only in the Nix shell.
+
+First off, you should install Nix and enable the Flakes extension
+
+```bash
+$ sh <(curl -L https://nixos.org/nix/install) --daemon
+$ mkdir -p ~/.config/nix
+$ echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
+```
+
+Now you can get into our Nix shell and use the tools you need to
+develop: Bash, git, MkDocs, etc.
+
+```bash
+$ cd nix
+$ nix shell
+```
+
+
+### Editing content
+
+The documentation site source is in the `docs` folder. Write in plain
+markdown. Use figures accordingly. Put images and binary resources
+in `docs/rsrc`. Respect the naming schema of the files in there to
+keep it reasonably organised.
+
+You can build the documentation site and live edit it easily with
+the `mkdocs` command. After getting into the Nix shell as explained
+earlier, go back to the repository's root directory and run
+
+```bash
+$ mkdocs build
+```
+
+This will output the whole static site in the `site` directory—there's
+a `.gitignore` file to keep this directory out of source control. To
+see what the site looks like, run
 
-It consists of an introduction, where the most important topics and ideas are
-briefly introduced, and a tutorial, where the user can get a first hands-on
-experience on the most important operations of the platform.
+```bash
+$ mkdocs serve
+```
 
-### Organisation
+and then browse to http://localhost:8000. If you edit files in the
+`docs` directory, your changes should be reflected in the browser.
 
-Documentation is found in the `docs` folder.
 
-Write in plain markdown. Use figures accordingly.
+### Deploying the site
 
-Images and binary resources are saved in `docs/rsrc` folder. Respect the naming
-schema of the files in there to keep it reasonably organised.
+To go live with your changes, first build the Nix package
 
-### Usage
+```bash
+$ cd nix
+$ nix build .#docs-site
+```
 
-1. Run `sh run.sh`
-1. Open `http://127.0.0.1:8000/` in your explorer and you should see the docs
-1. You can now edit them and changes will be reflected on the fly.
+then upload and extract `result/docs.tgz` to our Nginx machine
+serving `docs.orchestracities.com`.

docs/gravitee.md

@@ -11,7 +11,7 @@ in the Developer Portal and how policies and Oauth2 authorization are handled.
    It's worth reminding that the public clients set up in Keycloak will
    limit what the given tokens enable users to do, such as user management operations.
    The user requests a specific scope with the request (e.g. entity:read). A list
-   of scopes is available in the [**Keycloak Configuration**](/keycloak) section of this documentation.
+   of scopes is available in the [**Keycloak Configuration**](keycloak.md) section of this documentation.
 
 2. When then token is used, it is validated against Keycloak's confidential client
    (the resource-server client). The operation being attempted (e.g. creating an
@@ -58,7 +58,7 @@ The configuration contains:
 For each API endpoint, policies are in place for each operation. This enables API
 owners to decide exactly what scopes are required for users to perform different
 operations, whether is accessing, editing, creating or deleting resources.
-See the [**Keycloak Configuration**](/keycloak) section for more details on
+See the [**Keycloak Configuration**](keycloak.md) section for more details on
 client scopes.
 
 Policies follow a basic syntax of resource:operation, so for the /entities endpoint

mkdocs.yml

@@ -1,23 +1,29 @@
-site_name: "Orchestra Cities"
+site_name: Orchestra Cities
 site_url: https://orchestracities.com
-site_description: 'Orchestra Cities Documentation'
-site_author: 'Martel Innovate'
-copyright: 'Copyright © 2020 - Martel Innovate'
-theme: readthedocs
-#markdown_extensions: [toc,fenced_code]
+site_description: Orchestra Cities Documentation
+site_author: Martel Innovate
+copyright: Copyright © 2020 - Martel Innovate
+theme:
+  name: readthedocs
+  locale: en
 markdown_extensions:
-    - toc:
-        permalink: "#"
-    - fenced_code:
+  - fenced_code
+  - toc:
+      permalink: "#"
+validation:
+  links:
+    absolute_links: relative_to_docs
+    anchors: warn
+    unrecognized_links: warn
 docs_dir: docs
 nav:
-    - '0. Introduction': 'index.md'
-    - '1. Platform overview': 'overview.md'
-    - '2. Architecture': 'architecture.md'
-    - '3. Deploy an example instance': 'deploy.md'
-    - '4. Security configuration':
-      - '4.1. Auth Provider (Keycloak)': 'keycloak.md'
-      - '4.2. Api Management (Gravitee)': 'gravitee.md'
-      - '4.3. Admin Portal': 'portal.md'
-    - '5. Tutorial': 'tutorial.md'
-    - '6. How to contribute': 'contribute.md'
+  - 0. Introduction: index.md
+  - 1. Platform overview: overview.md
+  - 2. Architecture: architecture.md
+  - 3. Deploy an example instance: deploy.md
+  - 4. Security configuration:
+    - 4.1. Auth Provider (Keycloak): keycloak.md
+    - 4.2. Api Management (Gravitee): gravitee.md
+    - 4.3. Admin Portal: portal.md
+  - 5. Tutorial: tutorial.md
+  - 6. How to contribute: contribute.md

nix/flake.nix

@@ -0,0 +1,18 @@
+{
+  description = "Flake to build and develop orchestra cities docs.";
+
+  inputs = {
+    nixpkgs.url = "github:NixOs/nixpkgs";
+    nixie = {
+      url = "github:c0c0n3/nixie";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = { self, nixpkgs, nixie }:
+  let
+    build = nixie.lib.flakes.mkOutputSetForCoreSystems nixpkgs;
+    pkgs = build (import ./pkgs/mkSysOutput.nix);
+  in
+    pkgs;
+}

nix/pkgs/cli-tools/default.nix

@@ -0,0 +1 @@
+{ pkgs }: pkgs.callPackage ./pkg.nix {}

nix/pkgs/cli-tools/docs.md

@@ -0,0 +1,14 @@
+CLI Tools
+---------
+> Nix package docs.
+
+CLI tools to build and develop Orchestra Cities docs. These tools
+include all you need, even Bash, ensuring dev env reproducibility
+across different environments---Linux x86_64 and ARM64, MacOS Intel
+and Apple silicon. Have a look at [pkg.nix][pkg] to see what tools
+we bundle.
+
+
+
+
+[pkg]: ./pkg.nix

nix/pkgs/cli-tools/pkg.nix

@@ -0,0 +1,36 @@
+#
+# See `docs.md` for package documentation.
+#
+{ pkgs }:
+rec {
+
+  tools = with pkgs; [
+    bash
+    coreutils
+    curl
+    git
+    mkdocs
+    python3
+  ];
+
+  # Make a shell env with all the given programs.
+  # Notice we also add the program paths to the derivation so you can
+  # reference them later if needed. E.g. in NixOS
+  #
+  #    environment.systemPackages = pkgs.your-derivation.paths;
+  #
+  # See also NOTE (1) below.
+  mkShell = name: paths: pkgs.buildEnv {
+    inherit name paths;
+  } // { inherit paths; };
+
+  dev-shell = mkShell "dev-shell" tools;
+
+}
+# NOTE
+# ----
+# 1. `mkShell`. We roll out our own function to create a derivation to make
+# programs available in the PATH when instantiated through `nix shell`. This
+# is because the built-in `mkShell` only works with `nix develop`. See:
+# - https://github.com/c0c0n3/nixie/wiki/Fiddling-about-with-Nix-dev-envs
+#

nix/pkgs/docs-site/default.nix

@@ -0,0 +1 @@
+{ pkgs }: pkgs.callPackage ./pkg.nix {}

nix/pkgs/docs-site/docs.md

@@ -0,0 +1,16 @@
+Docs Site
+---------
+> Nix package docs.
+
+This package builds the a MkDocs static site from the markdown source
+in the `docs` directory. The static site files go in the `docs` output
+directory and also get packaged in a `docs.tgz` tarball for extra
+convenience---`docs` is also the root directory in the tarball.
+
+Have a look at [pkg.nix][pkg] if you're interested in the Nix package
+details.
+
+
+
+
+[pkg]: ./pkg.nix

nix/pkgs/docs-site/pkg.nix

@@ -0,0 +1,24 @@
+#
+# See `docs.md` for package documentation.
+#
+{
+  stdenv, mkdocs
+}:
+stdenv.mkDerivation {
+  pname = "docs-site";
+  version = "2020-07-26";
+
+  src = ../../../.;  # TODO: replace w/ GitHub when we have a release.
+
+  buildInputs = [ mkdocs ];
+
+  buildPhase = ''
+    mkdocs build
+  '';
+
+  installPhase = ''
+    mkdir -p $out/docs
+    cp -r site/* $out/docs
+    tar czf $out/docs.tgz -C $out docs
+  '';
+}

nix/pkgs/mkSysOutput.nix

@@ -0,0 +1,20 @@
+#
+# Function to generate the Flake output for a given system.
+#
+{ # System label---e.g. "x86_64-linux", "x86_64-darwin", etc.
+  system,
+  # The Nix package set for the input system, possibly with
+  # overlays from other Flakes bolted on.
+  sysPkgs,
+  ...
+}:
+let
+  docs-site = import ./docs-site { pkgs = sysPkgs; };
+  tools = import ./cli-tools { pkgs = sysPkgs; };
+in rec {
+  packages.${system} = {
+    default = tools.dev-shell;
+    dev-shell = tools.dev-shell;
+    inherit docs-site;
+  };
+}