OSHRePub

DOI

The Open Source Hardware REview and PUBlication platform will be an open source software to review and publish hardware documentation packages. The current version of the software facilitates reviews, we are hoping to develop the publication part soon.

It does so via two main components:

1. By integrating into the harwdare development process to provide automated design readiness checks.
2. By providing a manual design review process in the style of academic journals.

It is meant to be set up and run by community-trusted entites wanting to serve as quality guarantors.

Vision and goals

The software is meant to support hardware creators (authors) so their designs can be more easily reproduced, modified, and later republished. By recognizing documentation quality, it will facilitate the growth of communities around these hardware and make the work of the teams better recognized in the academic world.

Project and software overview

OSHRePub was designed inside the Open.Make project in Berlin. Moritz Maxeiner coded the tool using the phoenix framework for Elixir. See citation.Cff file to cite this work.

At runtime we use

• GitBuilding (version 0.14.9),
• osh-tool (version 0.5.0), and
• pandoc (docker image pandoc/latex:3.5).

Workflow of the review

The author is asked to add a metadata file to its repository (aligned with the LOSH metadata file). He can then request a review once he made a account on the OSHREPUB instance. The editor can start the review after seeing the automatic checks results. Invited reviewers give their comments. When the reviews are done, the editor start the anwer process and the author is then asked to update the repository and answer the comments. When done, he can ask the editor to start a second turn of reviews. The editor can signal the reviews are over and publish the hardware documentation package (along the review report).

In a future version, the publication will be automated via a bridge to a Dspace instance.

Design choices

We decided to:

• First implement a link to GitHub as most OSH projects are located there: auhtors are requesting the review of a specific commit.
• Using osh-tool for automatic checks
• Facilitate the review of project using the documentation tool Gitbuilding
• Use pandoc for the creation of review reports in pdf
• Implement questions inside the tool to guide the reviewers (question list is modifiable by the editor).
• Having a review in rounds, the authors responding to comments only when reviews are done.
• Reviewer comments are linked to one element of the documentation package and can be linked to questions.
• Relevant settings, such as the minimum osh-tool threshold for a project to qualify for manual review, are changeable at runtime.

Installation

To create a development instance of the OSHRePub, you need to set the development setup, build the runtime environement, integrate with your GitHub account.

To create a production instance, build a release, deploy this release to a server of your choice.

Development

Basic setup

We recommend to use Visual Studio Code (VSC) and its support for Development Containers:

1. Obtain a copy of the source.
2. Create a new file container/dev/secrets/env and set the password for development accounts with the following line:

   DEV_ACCOUNTS_PASSWORD=replace_me
   

   Replace replace_me with a secure password of your choice.
3. Open the project folder in VSC.
4. Use "Reopen in Container" to have VSC start building the required container images. This requires network connectivity and may initially require quite some time.
5. Set up Elixir dependencies in the terminal: $ (cd ~/workspace/app/ ; mix setup )
6. Create development accounts: $ (cd ~/workspace/app/ ; mix eval 'OSHRePub.Dev.create_accounts()' )
7. Start the platform in the terminal: $ (cd ~/workspace/app/ ; iex -S mix phx.server )

You should now be able to open localhost:4000 in a browser to access the platform.

Build required runtime components

Follow container/README.md.

GitHub integration

1. Create a new OAuth App.
2. Copy its Client ID and Client secret as new lines into container/dev/secrets/env:

   GITHUB_CLIENT_ID=Client_ID
   GITHUB_CLIENT_SECRET=Client_secret
   

3. Use the VSC command "Dev Containers: Rebuild Container"
4. Verify on the terminal with echo $GITHUB_CLIENT_ID

Build a release archive for production use

Execute the following in the app directory:

MIX_ENV=prod mix compile
MIX_ENV=prod mix assets.deploy
MIX_ENV=prod mix release oshrepub
MIX_ENV=prod mix phx.digest.clean --all

The generated release archive will be _build/prod/oshrepub-*.tar.gz

Operation

Basic setup

1. Obtain a copy of a release archive.
2. Extract the release archive into a new application directory.

   mkdir oshrepub; tar -C oshrepub -xf oshrepub-*.tar.gz
   

3. Set up a PostgreSQL database.
4. Create the following environment file as .oshrepub-env:

   export SECRET_KEY_BASE=
   export PGHOST=/run/postgresql/
   export PGUSER=
   export PGPASSWORD=
   export DATABASE_URL=postgresql:///${DB_NAME}?host=${PGHOST}
   export PHX_HOST=${DOMAIN}
   export PROJECTS_STORAGE_DIR=/srv/oshrepub/projects
   export WEBHOOK_HOST=https://${DOMAIN}
   export CHECK_ORIGIN=https://${DOMAIN}
   export GITHUB_CLIENT_ID=
   export GITHUB_CLIENT_SECRET=
   

   • You can generate an appropriate value for SECRET_KEY_BASE like this:

     openssl rand 64 | openssl enc -A -base64
     

   • The values for PGHOST, PGUSER, PGPASSWORD, and DATABASE_URL need to be set according to how you set up your PostGreSQL database.
   • ${DOMAIN} should be replaced with the domain under which the platform should be hosted, such as example.eu.
   • The GITHUB_* variables need to be set as described above under GitHub integration.
5. Run the database migrations:

   ( . ~/.oshrepub-env && oshrepub/bin/oshrepub eval 'OSHRePub.Release.migrate' )
   

6. Start the platform:

   ( . ~/.oshrepub-env && oshrepub/bin/server )
   

Build required runtime components

Follow container/README.md as found in the extracted location below oshrepub/lib/oshrepub-*/priv/.

Manually create an account

/path/to/oshrepub/bin/oshrepub eval 'OSHRePub.Release.create_account("admin@example.eu", "Admin", "password", [:admin])'

Use nil (no double quotes) instead of "password" to have a password be automatically generated and displayed (once).