lthms/nestling

nestling

nestlingcompilation fixes: Bump libpijul to 0.8.2.…on October 10, 2017
nestling-uifix(nestling-ui): Rename the source direct…on April 22, 2018
nestlingdcompilation fixes: Bump libpijul to 0.8.2.…on October 10, 2017
.ignoreAdd a .ignore fileon September 6, 2017
Makefilechore(build): Make make the primary build …on May 27, 2017
READMEfeat(nestling): get the list of branches o…on May 18, 2017
print.mkchore(build): Make make the primary build …on May 27, 2017
README
                        ━━━━━━━━━━━━━━━━━━━━━━
                               NESTLING
                        ━━━━━━━━━━━━━━━━━━━━━━

Table of Contents
─────────────────
1. Overview
.. 1.1. [nestling]
.. 1.2. [nestlingd]
.. 1.3. [nestling-ui]
2. Getting Started
3. Contributing



1. Overview
═══════════

  The current repository contains three projects:
  · [nestling] is a high-level and read-only api to work with pijul
    repositories
  · [nestlingd] is an HTTP server which serves a REST API to visualize
    the current state of given pijul repositories
  · [nestling-ui] is a webui written in Purescript

1.1. [nestling]
───────────────

  The main idea behind nestling is to provide a more usable and stable
  API than what libpijul can offer. It is important to understand that
  performance is not part of this crate goal. Of course, any
  contribution to improve that side of the project is welcome.

1.2. [nestlingd]
────────────────

  [nestlingd] is a HTTP server which exposes a read-only REST API to
  query the current state of a pijul repository. Under the hood, it
  uses rocket[1]. It can be configured dynamically thanks to a
  configuration file using the toml[2] configuration language.

  [1] https://rocket.rs
  [2] https://github.com/toml-lang/toml

1.3. [nestling-ui]
──────────────────

  The main webUI of the nestling is implemented using Halogen[1], a
  “declarative, type-safe UI library for Purescript[2].”

  [1] https://github.com/slamdata/purescript-halogen
  [2] https://www.purescript.org

2. Getting Started
══════════════════

  For now, [nestling] is not quite ready to be used in production and
  it is not straightforward to run.

  First, you need to build both the backend ([nestlingd]) and the
  frontend ([nestling-ui]). To do that, you will need:
  · make
  · rust-nightly, cargo
  · npm

  Building the nestling is as simple as

   ╭──────────────────────────────────────────────────────────────╮
   │ $ make                                                       │
   ╰──────────────────────────────────────────────────────────────╯

  This should succeed gracefully.

  Once it is done, you still need to configure your instance. You can
  do that by editing two files. The first one is the configuration
  file of [nestlingd]. Right now, the server tries to read 
  in the current working directory.

  An example of a configuration file can be found at
  .

   ╭──────────────────────────────────────────────────────────────╮
   │ title = "My Nest"                                            │
   │                                                              │
   │ [repos.nestling]                                             │
   │ name = "nestling"                                            │
   │ path = ".."                                                  │
   ╰──────────────────────────────────────────────────────────────╯

  Basically, you choose a label for you repository. This label will be
  use to identify the repository in the API routes. You give a more
  comprehensive name then, and its path.

  Then, you need to configure . This
  file is fetched by the frontend first to know where to locate the
  API. It needs to be a valid JSON file, so pay attention not to
  forget a coma or a quote. By default, the file is generated with
  development parameters.

   ╭──────────────────────────────────────────────────────────────╮
   │ {                                                            │
   │   "base": "http://localhost",                                │
   │   "port": 8000,                                              │
   │   "mount": ""                                                │
   │ }                                                            │
   ╰──────────────────────────────────────────────────────────────╯

  From the repository root, you can start the server as follows:

   ╭──────────────────────────────────────────────────────────────╮
   │ $ cd nestlingd                                               │
   │ $ cargo run nestlingd [--release]                            │
   ╰──────────────────────────────────────────────────────────────╯

  If you run [make] before, then [nestlingd] is already built in
  release mode.

  Then, you need to start a HTTP server to serve the frontend. The
  http.server module of python is a good candiade. From the repository
  root, just run the following commands:

   ╭──────────────────────────────────────────────────────────────╮
   │ $ cd nestling-ui/site                                        │
   │ $ python -m http.server 8001                                 │
   ╰──────────────────────────────────────────────────────────────╯

  You finally can visit your local webserver[1] to see the nestling in
  action.

  [1] http://localhost:8001/#r/nestling/branch/master

3. Contributing
═══════════════

  The nestling is an opensource and Free Software. It is distributed
  under the terms of the GPL-3.0 license. Feel free to contribute if
  you'd like! The nestling code base uses pijul[1] as its main DVCS.

  The branch “nestling-next” contains the patches which have been
  accepted and will be part of the next release. We do not unrecord in
  this branch, so if you want to contribute, it should be your
  “forking point”.

  Because pijul does not yet support tags, branches will be used
  instead. A branch “nestling-x.y.z” where x, y and z are all numbers,
  can be safely assumed to be “locked“. We will not push new patches
  to it and therefore it shall reflect the state of the codebase at
  the time of the release.

  [1] https://pijul.org