dehub/docs/tut1.md

Tutorial 1: Create Your Own Project

This tutorial will guide you through starting a dehub project of your own, as well as introducing some basic concepts regarding how commit payloads work. You will use an example hello world project to do this.

This tutorial assumes you have already completed Tutorial 0.

Step 0: Init the Project

A dehub project is initialized in the same way as a git project. An empty directory is created, and dehub init is run within that directory.

mkdir hello-world
cd hello-world
dehub init

dehub init does nearly exactly the same thing as git init, with the primary difference being that it sets the initial branch to be main instead of master. dehub makes a distinction between main and master in order to help prevent confusion between dehub and vanilla git projects, as well as to avoid conflicts when migrating vanilla git projects to dehub.

Step 1: Add the First Account

A dehub project is not fully initialized until it has an account defined for it. dehub accounts refer to a specific user who has some kind of access to the project. Each account can have specific permissions for it, as well as multiple ways of signifying itself.

For now, you'll add a basic account tut with a pgp key signifier. First, create the .dehub directory, which is where all dehub project configuration goes, and put your pgp key there:

mkdir .dehub
gpg -a --export KEY_ID > .dehub/tut.asc

Next you'll create the .dehub/config.yml file, which is where accounts are actually defined (amongst many other things). The file should have the following contents:

# contents of .dehub/config.yml
---
accounts:
  - id: tut
    signifiers:
      - type: pgp_public_key_file
        path: ".dehub/tut.asc"

Finally, you'll commit these changes and the project will have its first commit! Committing changes works very similarly to committing comments (as you did in Tutorial 0). Where a comment commit merely carries a user's comment, a change commit describes a set of changes to the tracked files in the git repo.

git add --all
dehub commit --as tut change

Like when you made a comment commit, this will pop up with your editor asking for a description of the changes. Fill it in with something like Initialize the project and save+close the editor. Depending on your pgp key settings you'll likely be prompted for your pgp key password at this point. After that the commit has been created!

Step 2: Inspect the Payload

In this step you're going to look at the commit you just created and learn about the contents of the payload. To view the commit do git show. Something similar to the following should be output as the commit message:

commit 3cdcbc19546d4e6d817ebfba3e18afbc23283ec0
Author: username <>
Date:   Sat Apr 25 15:17:21 2020 -0600

    Initialize the project

    ---
    type: change
    description: Initialize the project
    fingerprint: AG0s3yILU+0uIZltVY7A9/cgxr/pXk2MzGwExsY/hbIc
    credentials:
    - type: pgp_signature
      pub_key_id: 95C46FA6A41148AC
      body: BIG LONG STRING
      account: tut

All commits in a dehub project will contain a similar looking message. The first line (the head) is always a human readable description of the commit. In this case our commit description itself, Initialize the project, was used.

After the head comes the payload, which is always a YAML encoded object. All payloads have a type field indicating what type of payload they are. That type will determine what other fields the payload is expected to have. The other fields in this payload object are:

• description: This is the description which was input into the editor when creating the change commit.

• fingerprint: A unique descriptor for this set of changes. It is computed using both description and the files changed.

• credentials: A set of credentials for this commit, each one declaring that this commit has been given approval by a user. This commit has one pgp_signature credential, created by the tut account. The body is a signature of the fingerprint created by the tut's pgp key.

Step 3: Create Another Commit

Now that the initial commit is created, and configuration has been added to the dehub project, you can continue on to use the project for what it was intended for: greeting the world!

Add a simple "hello world" script to the project by doing:

echo 'echo "hello world"' > hello.sh
git add hello.sh
dehub commit --as tut change --descr 'add hello.sh'

You'll notice that this time around you used the --descr flag to declare the change's description, rather than opening up the editor

Once again you can inspect the payload you just created using git show, if you'd like, or continue on to the next step to learn about commit verification.

Step 4: Verify Your Commits

All this work to create YAML encoded payloads has been done for one primary purpose: to make commits verifiable. A verifiable commit is one which follows the access controls defined by its parent.

Your dehub project doesn't have any explicitly defined access controls (that will be covered in a future tutorial), and so the defaults are used. By default, dehub requires that all commits in main are change commits which have been signed by at least one account.

In order to verify the HEAD commit you can do:

dehub verify

This command looks at the project configuration defined in the parent of HEAD and verifies that HEAD conforms to it. The HEAD of your project is a change commit signed by the account tut, and so should be verifiable.

Arbitrary commits can be verified using the --rev flag. This command will verify the parent of HEAD, i.e. the initial commit:

dehub verify --rev HEAD^

The initial commit doesn't have a parent, and so is a special case for verification. The initial commit uses the configuration defined within itself in order to verify itself. This creates an exploit opportunity: if you clone a remote dehub project and an attacker intercepts that request they will be able to send you back a project with a different initial commit than what you expected. The whole project will still be verifiable, even though it's been compromised. For this reason it's important to manually verify that the initial commit of projects you clone are configured correctly, using the expected signifiers for the expected accounts.

You are now able to initialize a project, configure accounts within it, commit changes to its files, and verify those commits. Well done! Continue on to Tutorial 2, where you will learn how to configure dehub's access controls.