This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

@platform Additional Resources

All the resources you will need for developing on the @platform

1 - Step-by-step dess guides

Learn how to setup dess on a specific platform

1.1 - Setup dess on AWS (Amazon Web Services) Platform

Step-by-Step setup of dess on AWS (Amazon Web Services)

Step-by-Step setup of dess in AWS

In this step-by-step guide I will walk you through all steps required to setup your own private dess using AWS. Please use the index to skip some steps in case you have already completed them.

Table of contents

Pre-requisites

  • Registered @sign(s) to setup
  • An AWS account
  • A Fully Qualified Domain Name (FQDN)

1. Registering your @sign

This topic is already well documented. Please follow the guidance of Our FAQs and register via the registrar site.

2. Sign-up for AWS account

If you are new to AWS, signing up for an account is free! The cost of running dess is about 10$/month. You can create your account at https://aws.amazon.com/ and as of June 6th, 2021 there is a “free tier” available which was used during the making of this guide.

aws-free-trial

Follow the instructions on screen.

aws-sign-up

Once you are done with registration, you will be able to login to your aws console.

Make sure that you select the correct region in the top right corner.

aws-region

Select the region that is geographically closest to your location for best performance.

You are now setup on AWS and ready to prepare dess.

3. Register your own fully qualified domain name (FQDN)

This step can be performed at a variety of sites, all with different pricing models. You can use sites like Go Daddy, Namecheap, and many others. However, since we have AWS account, we can use it to register our domain through the Route 53 service.

In your AWS console navigate to services in top left corner and select Route 53.

a) Register domain name with AWS.

In your AWS console search for Route 53.

aws-route53

You can start looking for your domain directly from here:

image-20210726083635919

Based on the domain name you search, AWS will give you similar options, and their pricing. As I am looking for the best deal, the .link domain seems like a good option at a cost of 5$ / year.

In my case 4atsign.link is free and I will register it by clicking “Add to cart” and continue.

img

Fill out DNS registration form:

img

Continue review details and order. At this point if all is fine you should see your domain request pending:

img

This can take some time so why don’t we move on to next step!

4. Preparing AWS instance

Now since I am new to AWS, the easiest way to get started is by using the LightSail service from service catalog. This will enable you to deploy small system which is more then capable of handling dess at pre-set price.

img

Welcome to LightSail:

img

First step is to create new instance. Fortunately, we have big orange button that can do just that!

There are several options we are presented at this moment. Since I am living in Europe I select “Frankfurt, Zone A (eu-central-1a)” as my instance location. Instance region will dictate how well will your instance response based on your geographical location. People located in India should selects APAC region where as people in US should select North America region. You can leave availability zone set as default.

img

Next up will be selection of operating system we want to deploy. We know that dess works well with Ubuntu 20.04 LTS so lets select just that.

img

You are presented with couple more options, but unless you know what you are doing leave these as is.

img

Now let’s select instance plan. dess is relatively light weight so for testing purposes I will select first instance plan for 3.5$/Month. This will provide us with 512 MB of RAM, 1vCPU, 20GB of storage and 1TB of data transfer. This is more then enough to run our dess.

img

Lastly we have to name our instance. This is the name you will be presented with in your dashboard.

img

Last but not least is to press “Create instance”

img

After a couple of seconds you should be re-routed to your dashboard and see your instance up and running:

img

5. Preparing your instance for network access

a) Assignment of Static IP

Next up, is to provide our instance with a static IP and linking our domain to it.

When you click on your instance name, it will take you to the management console, which should look like this:

img

This is where you control hardware, connectivity and if needed can delete your instance.

Lets configure a static IP address for your new instance. Navigate to Networking and click on Create static IP:

img

Our region and instance is selected, so the only thing left is to name our static IP. I selected the name atsign-static, but it can be any name you like.

img

Lets hit create:

img

And voila, we now have a static IP address on the internet and it will not change. Now we can link our domain name with it.

img

When you click on your instance name and navigate to Networking, the static IP is now assigned.

img

b) Assignment of Domain name to your static IP

We can now move on to linking our static IP address to our domain. This is done via the AWS console which can be accessed in the top right of Lightsail.

img

Verify your email used for registering domain:

By now you should receive verification email that will confirm registration of your domain. Click this link before moving on.

Linking domain with your static address:

Lets navigate to “Route 53” from Services menu.

img

From your dashboard click on “Domain” which will take you to the “Registered Domains” tab.

img

Here you can click on your registered domain which will take you to overview page with domain status and contacts.

img

Click on “Manage DNS”

img

And click on your domain name.

This will show you your DNS records for your domain. We now need to link A type record to your domain linking it to IP address of your instance.

This is done simply by typing your static IP address from previous step into field “Value” and clicking Create record:

img

If everything goes well you should see following in your domain dashboard:

img

To test if you are successful open command line and ping your domain. You should see your instance static IP address. It will not respond which is normal due to IPv4 firewall. It is actually good thing!

img

At this point we have created DNS record we will use to link our dess, we created instance name which will be running our dess and we have opened port range which is exposed to the internet and we can communicate with @sign root server and our apps with.

c) Setting up Firewall

Next up we need to make sure we have ports open for our dess to communicate with root server and our apps. In Section networking go to section “IPv4 Firewall” and click “+ Add rule” Our rule will be “Custom” on TCP protocol with Port range in number higher then 1024. In my case I have selected port range 8000-8010. This will enable me to run up to 10 @signs in parallel.

img

Click create and verify that your new rule is in list:

img

6. Instance setup and dess deployment

Open your LightSail console

By now you should see your instance in “Running state”

img

Open it and on tab Connect click on “Connect using SSH”

img

You should be presented by a new window with command line:

img

Before we do anything else, we should update the system:

sudo apt update && sudo apt upgrade

This might take some time, but it will make sure we have latest repository information and the system is up to date.

Next make sure curl is installed, we will use curl to pull the dess installation file:

sudo apt install curl

Finally, run the dess installer:

curl -fsSL https://getdess.atsign.com | sudo bash

Once the installer is finished you should be prompted like so:

Dess installed, please move on to the sudo dess-create command.

7. Registration of @sign in your private dess

At this step you should already have your @sign registered at http://atsign.com. If not go do it!

I have registered my own free @sign (@44likelycanary) which I will link to my dess.

In your instance console, navigate to dess folder. If you were following this guide it will be located in:

We now need to create the service that will host our @sign by executing the dess-create command:

$ sudo dess-create @44likelycanary 4atsign.link 8000 <email address> likelycanary

To make it more understandable:

I will be registering my @sign @44likelycanary.

I will be using my domain 4atsign.link which I have registered through AWS.

I am using port 8000 which I have opened in my instance firewall.

My registration email address is <email address> (this email is used to sign the SSL certificates).

The last likelycanary is the name that docker will use to track the service.

If everything is successful you should see output like this:

img

At this moment your @sign is registered on your dess.

8. Activation of @sign

Next up we need to activate it

Login to your dashboard at https://my.atsign.com/dashboard

Open “my @signs”

img

Open “managed” of @sign you are registering”

img

Navigate to Advance settings:

img

If you have already activated your @sign you will be prompted to erase all your data first

img

Once done you are able to link your @sign with your private dess. Use your domain and port number with which you have created service on your cloude instance and press Activate.

img

You should see that your @sign is being activated in your dashboard:

img

This can take several minutes so go get cup of coffee, some tea maybe, stretch your body and pray you haven’t made any mistakes!

Once the activation process completes you are welcomed by green Activated.

img

You can now open @buzz or @wavi and register your @sign via QR code and generate your keys!

CONGRATULATIONS

1.2 - Setup dess on GCP (Google Cloud Platform)

Step-by-Step setup of dess on GCP (Google Cloud Platform)

dess stands for “Distributed Edge Secondary Server” and it is used to host your @signs on your own secondary server. Refer to the Setup dess guide under Options to learn more.

In this step-by-step guide we will walk you through all steps required to setup your own private dess in GCP cloud from scratch. Please use index to skip some steps in case you have done them in another way.

Table of contents

Pre-requisites

  • Register Atsign at http://atsign.com
  • Have google account
  • Have registered Fully Qualified Domain Name (FQDN)

1. Registering your @sign

This topic is already well documents. Please follow guidance of https://atsign.com/faqs/ and register via https://atsign.com/get-an-sign/.

2. Sign-up for GCP account

a) Account creation

If you are new to cloud like me and need to create new GCP account, I have good news! The creation is for free. As promotion all new customer will also receive 300$ as credit. That is more than enough to run multiple dess’s for 3 months of offer validity.

gcp-discount

You can register with your gmail account or create new one by clicking “Get started for free” and follow instructions to register

Get Started

Once done with registration you will be able to login to your https://console.cloud.google.com/ And voila you have your GCP account up and running.

b) Setting up billing

To be able to run some services you have to maintain billing account. Navigation Menu -> Billing

gcp-navigation-billing

By default GCP creates “My Billing Account” which you can link to your project.

gcp-billing_project

Click “Link Billing account” and select “My billing account” from drop down

🔴 Its important to note that this account holds your 300$ free credits! 🔴

We are all setup and ready to go deploy!

3. Register your own fully qualified domain name (FQDN)

This step can be performed at range of different sites with different pricing models. You can use sites like http://www.godaddy.com; https://www.namecheap.com/; and many others. Since we have GCP account we can use it to register our domain through Cloud Domain.

a) Register domain name with GCP.

In your GCP console search for Cloud Domain.

gcp-search-domain

We first need to enable this service.

gcp-domain-api

Once the service activates you will be presented with its dashboard.

Lets register our fully qualified domain name (FQDN) that will be used for registration of our dess.

Click on “Register Domain” and look for suitable name.

gcp-domain-register

Reviewing pricing options of GCP .pw is their cheapest option which will work for testing. For my test case I am selecting atsign.pw with price $0.75 / month by clicking add to cart button and continue.

gcp-domain-lookup

Next we can select where will our DNS record be hosted. Simply select “Use Google Domains” and DNSSEC “Enabled” and click continue.

gcp-domain-config

We have no options with Privacy protection so simply click continue.

gcp-domain-privacy

Fill out contact details and click register. This will trigger registration email you will have to verify.

gcp-domain-contacts

Once you verify your email your domain should be ready to use

gcp-domain-status

b) Create Cloud DNS zone

Next step is to enable Cloud DNS service. Search for DNS in search bar and select Cloud DNS

gcp-search-dns

If its your first time activating this service you will have to enable the API. Press enable and wait for the activation to finish.

gcp-dns-api

Lets crate new DNS zone by clicking “Create Zone”

gcp-dns-create

We will select zone type as Public since we will be connecting to our DNS from internet and provide your registered DNS name. In my case atsign.pw. DNSSEC will be set to off and provide some meaningful Description. Once you filled all your details press create.

gcp-dns-create-details

You should receive following message:

gcp-dns-confirm

4. Preparing GCP instance

Now since I am new to GCP the easiest way to start using it is with prebuild solutions. This way you will deploy small system which is more then capable of handling dess at pre-set price.

We can use pre-build “Ubuntu 20”. In Search bar look for Ubuntu20

gcp-search-ubuntu20

🔴 Make sure to use “Ubuntu 20” and not “Hardened Ubuntu 20”. Although the Hardened version will work as well it requires additional manual steps to make work.🔴

This will take you to this prebuild solution overview page:

gcp-ubuntu20

Select launch

gcp-ubuntu20-api-enable

And press enable all required API’s

gcp-ubuntu20-api-enabled

Once all API’s are activated you are taken to configuration page:

gcp-ubuntu20-type

Prices are based on region and power of selected Virtual Machine (VM). To cost optimize you can select US region / N1 / g1-small at cost of $15/Month.

Next up is boot disk which we can leave as is.

gcp-ubuntu20-disk

This will deploy your Ubuntu 20.04 virtual machine.

gcp-ubuntu20-confirmation

5. Preparing your instance for network access

a) Assignment of Static IP

Next up our list of activities is providing our instance with static IP and linking our domain to it.

GCP assigned ephemeral IP address to our newly created VM. We need to change it to static IP.

In search bar look for External IP addresses.

gcp-search-networking

You should see your external IP address assigned to your VM

gcp-networking-overview

In column Type select ephemeral and change it to Static

gcp-networking-type

Give your static IP name and some description.

gcp-networking-static

Type should now say Static

gcp-networking-type-change

b) Assignment of Domain name to your static IP

Next step is to point your domain to your virtual machine running dess.

Search for Cloud DNS

gcp-search-dns

Open zone you have created in step 3.b Create Cloud DNS zone

gcp-dns-status

We now need to link A type record to your domain linking it to IP address of your Virtual machine.

This is done simply press “Add record set”

gcp-dns-add-record

Select Resource record type “A” and IPv4 address the address of your dess virtual machine.

gcp-dns-a

If everything goes well you should see following in your domain dashboard:

gcp-dns-status-final

Next step is to update Google Name servers. You can follow Googles guide - step 5.

https://cloud.google.com/dns/docs/tutorials/create-domain-tutorial#register-domain

To test if you are successful open command line and ping your domain. You should see your instance static IP address.

gcp-dns-test

At this point we have created DNS record we will use to link our dess, we created instance name which will be running our dess and we have opened port range which is exposed to the internet and we can communicate with @sign root server and our apps with.

c) Setting up Firewall

Search for Firewall in search bar.

gcp-search-firewall

Click on Create firewall rule

gcp-firewall-create

Lets create firewall rule that will enable the @sign root server communicate with our dess.

gcp-networking-firewall-settings

Important things to note:

  1. Ingress translates to incoming traffic.

  2. Selecting IP range as 0.0.0.0/0 will allow traffic from anywhere on the internet.

  3. For my use case I will enable port range 8000 – 8010 allowing me to register up to 10 @signs.

gcp-firewall-ranges

Press create and validate that your new rule appears in list of firewall rules.

gcp-firewall-status

Second we need to create firewall rule that will enable your dess server to communicate with certification authority.

gcp-networking-firewall-80

Important things to note:

  1. Ingress translates to incoming traffic.

  2. Selecting IP range as 0.0.0.0/0 will allow traffic from anywhere on the internet.

  3. You need to enable port 80 for communication with Certification authority.

gcp-networking-firewall-range-80

Press create and validate that your new rule appears in list of firewall rules.

gcp-firewall-status

6. Instance setup and dess deployment

Open your GCP console at https://console.cloud.google.com/compute/instances and search for VM instances

gcp-search-vm

By now you should see your instance in “Running state”

gcp-vm-status

Click on the SSH button and connect to your instance.

You should be presented by new window with command line:

gcp-vm-connected

Before we do anything else, we should update the system:

sudo apt update && sudo apt upgrade

This might take some time, but it will make sure we have latest repository information and the system is up to date.

Next make sure curl is installed, we will use curl to pull the dess installation file:

sudo apt install curl

Finally, run the dess installer:

curl -fsSL https://getdess.atsign.com | sudo bash

Once the installer is finished you should be prompted like so:

Dess installed, please move on to the sudo dess-create command.

7. Registration of @sign in your private dess

At this step you should already have your @sign registered at http://atsign.com. If not go do it!

I have registered my own free @sign (@44likelycanary) which I will link to my dess.

In your instance console, navigate to dess folder. If you were following this guide it will be located in:

We now need to create the service that will host our @sign by executing the dess-create command:

$ sudo dess-create @44likelycanary 4atsign.link 8000 <email address> likelycanary

To make it more understandable:

I will be registering my @sign @44likelycanary.

I will be using my domain 4atsign.link which I have registered through AWS.

I am using port 8000 which I have opened in my instance firewall.

My registration email address is <email address> (this email is used to sign the SSL certificates).

The last likelycanary is the name that docker will use to track the service.

If everything is successful you should see output like this:

img

At this moment your @sign is registered on your dess.

8. Activation of @sign

Next up we need to activate it

Login to your dashboard at https://my.atsign.com/dashboard

Open “my @signs”

gcp-atsign-dashboard

Open “managed” of @sign you are registering”

gcp-atsign-nonactive

Navigate to Advance settings:

gcp-atsign-active

If you have already activated your @sign you will be prompted to erase all your data first

gcp-atsign-erase

Once done you are able to link your @sign with your private dess. Use your domain and port number with which you have created service on your cloud instance and press Activate

image-20210617111907819

You should see that your @sign is being activated in your dashboard:

gcp-atsign-activating

The activation will be completed once you have used your QR code from dess and retrieved your keys.

Once the activation process completes you are welcomed by green Activated.

gcp-atsign-activated

CONGRATULATIONS

2 - The @platform data privacy & permissions guide

The @platform data privacy and principles which assure that people always have control over their data

Application Access to Data

There are three basic types of application data access:

  1. Storing and retrieving data for your application
  2. Accessing data shared by others
  3. Accessing and reasoning over data stored by other applications

Storing and retrieving data for your application

If your application needs to store data, you can use the @SDK to manage data securely and easily in the @persistence keystore. This SDK provides the following capabilities:

  • Data is stored in an encrypted keystore locally for your application
  • Data access is in-memory and super-fast
  • Offline access with the device is supported
  • Data is synchronized and backed up to a cloud @server automatically
  • Data is synchronized across all the person’s devices automatically
  • Privacy is hardcoded: The owner of the data controls all access to it

Note: the cloud @server does not have access to the secret private key. This prevents bad actors from accessing or modifying private data not meant for them.

Creating, updating and deleting data with your application

Data operations that involve writing data to the @persistence keystore can only be done with the approval of the owner. Access to this data is cryptographically controlled. This is managed for your application by the @SDK and is remarkably easy. The types of access that can be set for each data record include:

  • public: data that can be read by anyone without need for authentication
  • shared: data that the owner has explicitly granted the right to some entity to read it after proving they are who they claim to be
  • private: data that is only accessible to the owner (requires authentication)
  • hidden: publicly readable data that is not listed in a scan of the keystore.

Naturally, the owner of an @persistence keystore has access to any and all data that is contained therein. After being authorized, your application can read the data that it needs from the keystore as well. Applications that prefer to rely on data within its own namespace can also store read data from the @persistence keystore with approval of the owner. As always, all data stored is owned and controlled by the owner of the @persistence keystore.

For more information on how your application can create, update, or delete data, see the @Persistence Keystore Guide and the @Protocol Verbs.

Accessing data shared by others

Applications typically are a combination of an owner’s data and data that has been shared with them by others. This is a new feature and is what we’re referring to when we talk about P2P (Peer-to-Peer) applications.

For example, messaging applications available today involve a combination of data (messages) from various people but have no way to ensure that each individual message belongs to its creator. With the @protocol, messages that I create and share with other people are owned by me and likewise, messages that others create and share with me are owned by them. The messaging application is thus responsible for interleaving and presenting these messages while simultaneously maintaining privacy controls for the owner of the data (i.e. I own my messages to you and you own your messages to me).

While this may seem confusing and difficult at first, the @Client SDK and the Flutter UI Component libraries make it very simple to implement. This results in surveillance-free, privacy-compliant applications that are simple, cost-effective, and efficient, with better performance than backend server-based applications of the past.

The @Client SDK provides the following capabilities that help to integrate data shared by others in your application:

  • Public data shared by others can be looked up
  • The notification verb alerts your application when new data shared by others is available
  • The monitor verb creates a persistent connection for real-time interactions
  • Data can be scanned for and read directly from another persons @persistence keystore
  • Shared data is cached for fast, reliable access to shared data with all privacy related parameters managed for you by the @Client SDK

For more information on how your application can create, update, or delete data, see the [@Persistence Keystore Guide](Persistence Keystore Guide) and the @Protocol Verbs.

Accessing and reasoning over data stored by other applications

One super interesting side effect of giving people control of their data and storing it all in one place is that any application that they authorize can reason over any data that they are allowed to access. Applications that are certified as @protocol compliant (@pps) can provide amazing new experiences because they have the ability to access and reason over all data stored in an @persistence keystore.

For example, a certified messaging app may contain a thread where a group of people are discussing which movie to go see on Wednesday night. If permitted, this information can also be presented as an event in their certified calendar application and similarly presented as a group in their certified contacts application.

Advanced Options

Create a separate @persistence keystore for your application (certification not required)

If you would like to store application data, you are free to use the @persistence keystore for your persistence if you want to. You may want to get your application certified anyways to advertise that it is privacy compliant and have it included in our list of certified apps.

Authentication only, without the @persistence keystore (certification not required)

If your application does not require data persistence on behalf of the person using it; for example, if you just want to make sure that your application is licensed to the person using it, then you do not need to get it certified. You may want to get your application certified anyways to advertise that it is privacy compliant and have it included in our list of certified apps.

For more information about getting your application certified, see the Certification page.

3 - The @platform persistence keystore guide

How to use the @platform encrypted key/value store

Application data storage

Data for your application is the combination of the device owner’s data with data that has been shared by others. An @sign owner’s data is…

  • Stored in the the @sign owner’s device’s (local) @persistence keystore
  • Accessed by others via their internet addressable, always-on, secure, cloud (remote) @server
  • Backed up in their secure cloud (remote) @server
  • Synchronized between their cloud (remote) @server and any other devices that belong to the owner
  • Secured by secret keys which are only stored on the @sign owner’s device’s keychain

Note: The @sign owner’s cloud (remote) @server does not hold the owner’s secret key, which is required to make changes to the data. The local @server on the owner’s device must initialize any data changes.

Data that others have shared with an @sign owner is…

  • Accessed directly from their secure cloud (remote) @server with full privacy controls so it is always up to date
  • Cached on the @sign owner’s device’s local keystore if permitted
  • Removed from the @sign owner’s device’s local keystore automatically according to the permissions set by the owner of the data
  • Updated upon change automatically using the notification verb

How application data is stored and retrieved

As mentioned above, data is stored encrypted as a key/value pair. The @Client SDK supports a familiar set of methods to store and retrieve data from an @persistence keystore. You should always keep in mind that the @protocol includes strict privacy controls applied to all data in an @persistence keystore.

Application Access

Apps can reason over all of my data in my @persistence keystore

One super interesting side effect of giving people control of their data and storing it all in one place is that any application that they can choose to reason over any data that they are allowed to access in order to create altogether new user experiences.

For example, their certified messaging application may contain a thread where a group of people are discussing which movie to go see on Wednesday night. If permitted, this information can also be presented as an event in their certified calendar application as well as a group in their certified contacts application.

Access within an application namespace

Applications that only rely on data within its own namespace can also store data in the @persistence keystore if certified as @protocol compliant. If the data being stored rightfully belongs to the person creating it (which is the case most of the time), then they will have control of how it is used and shared with other entities and applications.

Use a separate @persistence keystore for your application (certification not required)

If you would like to store application data, you are free to use the @persistence keystore for your persistence if you want to. You may want to get your application certified anyways to advertise that it is privacy compliant and have it included in our list of certified apps.

Authentication only, no need to use the @persistence keystore (certification not required)

If your application does not require data persistence on behalf of the person using it; for example, if you just want to make sure that your application is licensed to the person using it, then you do not need to get it certified. You may want to get your application certified anyways to advertise that it is privacy compliant and have it included in our list of certified apps.

For more information about getting your application certified, please see the Certification page.

4 -

Contributing to an Open-Source GitHub Project

Overview:

There are a countless number of open source projects that exist on the Internet, but just how are you meant to add anything to these? What does forking a repository mean? What is a pull request? How can you make a contribution?

What is an open source project?

For anyone who is new to not just software development but project management in general, an open source project is that of which any person has access to all of the details of the project and are free to utilize it, use it for research purposes, make modifications to it, and even distribute it elsewhere. GitHub of course, being one of the main wellsprings of open source projects! For the sake of this article, I will be using The @ Company’s atsign-foundation repository to explain any examples.

Why would you want to contribute to an open source project?

With the new, blossoming field of data science, being capable of finding your way around a GitHub project is a significantly useful skill in today’s world. You’ll find that many corporate entities will highlight your contributions to any GitHub project (as long as you have listed them within your résumé!). You’ll also find that there are many friendly developers who really appreciate the people who add modifications to the project, and especially if that modification comes with a flagged issue (there seems to be a special place in the heart of a developer for people who raise issues within their code)! There’s also this sense of great accomplishment when you can add something useful to a project, more importantly, for the projects that you use often.

How can you contribute to an open source project?

Choosing a Project:

The first step in contributing something to a project is knowing what project you will contribute to! I’d personally recommend thinking about a project or an idea you have familiarity with as this will greatly assist in understanding what the project’s purpose is.

Forking a Repository:

What is forking? In simplest terms, forking a project is simply making a copy of it to your own GitHub profile. GitHub allows anyone to fork a repository and this will allow you to do whatever you please with the entire repository without making any actual changes to the real project! Imagine it as taking a picture of a tree. You can make edits to your photo to make the tree look purple or to give it a face, but you won’t make any changes to the actual tree!

How to Fork a Repository:

First, navigate to the home page of the repository you wish to fork. Refer to the screenshot below:

Here, you can see that I am currently within the atsign-foundation’s ‘at_demos’ repository.

fork-button

If you look at the top right corner of the repository’s page, you’ll notice the ‘Fork’ button and a number next to it. That number represents the number of times this specific repository has been forked. Once you select the Fork button, GitHub will prompt you which repository you wish to fork to. My go-to option is typically my own profile, where it will create an entire repository under your profile name so that you may make whatever modifications you wish. After you choose what location you wish to fork to, GitHub will do all of the hard work for you. After a few seconds or so (depending on your Internet connection speed), you’ll find that the entire repository that you forked, is now copied to wherever you told GitHub to fork it! Congratulations! You’ve forked a repository!

Make Modifications to the Repository:

Now, you can do whatever your heart so desires with the project! Depending on what the project is, you may wish to clone the repository to your local machine using https/, or simply commit changes directly on your forked repository (totally your choice/preference!).

Creating a Public Key with GitHub

We recommend git cloning the repository using the SSH key option. You can set up your own public keys on GitHub quite easily. If you see below, you will see the Clone options, ‘HTTPS, SSH, and GitHub CLI’. Select the ‘SSH’ option and this will provide you a password-protected SSH key to git clone the repository.

GitHub-Code-Options

In order to create a public key on your machine, open any UNIX terminal and type the command:

ssh-keygen

From here, it will ask you to choose a lcoation to store the key. We suggest just clicking ‘enter’ on whatever location is chosen for you. It will then ask for a passphrase, we STRONGLY recommend clicking ‘enter’ again to not input a passphrase. After doing this, it will ask you to input the passphrase again and click ‘enter’ without inputting anything. After having successully creating the key, enter the command:

cat ~\.ssh\id_rsa.pub

This will print out your public key. Copy the entire thing, including the ssh in the beginning and whatever the final character is and navigate to your GitHub settings page. Within your settings, you will see a tab titled, ‘SSH and GPG keys’. Once you navigate to this page, you should see a green bottom near the top-left titled, ‘New SSH key’. Once you have clciked this and navigated to the new SSH Key page, you will have to input a name for the key as well as pasting the retrieved key copied from the above command. After you have done both of these things, you can finish with the ‘Add SSH key’ button and you will now be able to git clone in your terminal with the SSH URL.

Create a Pull Request:

After you are satisfied with the changes you have made to the project and are confident that this change will be beneficial to include, all you now have to do is create a pull request within the project’s real repository. GitHub has made it very simple to create a pull request for comparing forks. Refer to the screenshot below:

pull-request

You may notice, in the top left corner of the repository, you will see the ‘Pull requests’ option. After selecting this, you will be taken to the Pull Requests page. This page will show you every pull request that has been created for the specific repository. If you see below, there has been one pull request for this repository thus far.

pull-request-page

If you are sure you are ready to create a new pull request, simply click the ‘New pull request’ button. This will then navigate you to the compare page. If you followed the above steps, you would want to ‘compare forks’, which will be a small hyperlink as circled below:

compare-changes

This will now change the base and head repositories that will be compared. Be sure to select the correct branch of the real project that you wish to make a pull request for. Select the same repository you forked and the correct branch as the ‘base’ repository and ‘base’ branch. You may need to contact the project leader or one of the main developers if you need assistance for which branch you need to make a pull request for. After selecting these, be very careful in selecting the repository that you forked. This will be where you had made the modifications. Select this repository as the ‘head’ repository and ‘compare’ branch.

review-mods

From here, you will see all of the modifications that will occur if your pull request is accepted. Once you double check all of these modifications and are confident in it, you may now select ‘Create pull request’. You may notice that mine says ‘View pull request’ but that is because I have already gone through this process and have successfully created one.

Side note: Be sure that your contribution will be useful for those who utilize the project! If you do end up creating a pull request with your modifications, make sure that those modifications are properly documented in both the code and/or the comment section of the pull request itself.

5 -

Working With Hugo (Static Webpage Generator)

Overview:

Hugo, an open-source static website generator, is a new way to create web pages easily with flexible thematic capabilities. How do you get started with it and how can you go from beginner to confident?

What is Hugo?

Hugo is a static site generator that can be seen as a competitor for WordPress and Bootstrap. The best part about Hugo that differentiates it from its competitors is that it is an open-source project, which means it’s free to use! Hugo also makes content management a headache-free, comprehensive process! Hugo can be incredible for this type of content management due to not even needing to write HTML if web development is not something you’re comfortable with! If you are the type who really enjoys getting your hands dirty, Hugo’s flexibility expands to allowing developers to completely modify everything about their own static web page. Now what’s a static web page? You can pretty much sum it up to be a hard-coded page of information that, of course, does not change dynamically. The best advantage that static web pages have over dynamic web pages is the extreme difference in speed. Because most dynamic websites are producing content for the individual visitor, it can take much longer to produce the content.

There’s a growing community behind Hugo with numerous Stack Overflow locations with any questions relevant to that of Hugo. Getting Started with Hugo:

Windows:

Installing Hugo on Windows:

There are a few ways in which you can get started with Hugo, however the easiest way I have found to getting started and jumping straight into things is by the following steps:

Create a directory in a location on your drive. For me, I have more storage capacity within my D: drive so I navigate to my D: drive within my File Explorer and simply right click and select ‘Folder’. This will create a new folder wherever you were within your drive. Next, rename this folder to ‘Hugo’. After this, navigate inside of your Hugo folder and create another folder within it, this time calling it ‘bin’.

You’re now ready to download Hugo on to your machine. As most projects which are open-source can be found on GitHub, so can Hugo’s releases. In any web browser, navigate to the GoHugoIo repository. Here, you will find a great list of all of the releases catered for Windows, Linux, and MacOS. Be sure to select a release that has your operating system in the title. For example, I am using a Windows 10 machine that runs a 64 bit processor. So I navigated to the zip file titled hugo_extended_0.83.1_Windows-64bit.zip. (Note: the release number may be different from the one listed above due to the time at which I have written this document. You may also noticed that I have chosen the extended Hugo version. Hugo extended has more capabilities, especially for thematic purposes. Hugo’s extension comes with a few advantages such as; SASS/SCSS support, Minify javascript and css, resource catenation, source mapping, image processing and so much more. A more in depth view of it can be found here.

Once you have found the matching release title for your machine, feel free to simply download the zip file. Where you download the zip file does not matter, however, where you extract it does. When your download is complete, select ‘Extract all’ and be sure that you extract the contents of what you downloaded into the ‘bin’ folder that exists within your Hugo folder. Once the extraction is complete, it should look something like this:

bin-folder

For the release that I have downloaded and extracted, there are three files. Perhaps in a later release of Hugo, there may be more files included, but for now, as long as you have the application file titled ‘hugo’, you will be fine. If, for whatever odd reason, the ‘hugo’ file is titled something else, be sure to rename it to ‘hugo’ (note the lowercase ‘h’). There is also a license file and a readme. It is completely up to you if you read the readme and license files.

Determining if your Installation on Windows was successful:

Apologies in advance for MacOS and Linux users as I will be demonstrating the following steps using a Windows 10 machine. A later edit with both MacOS and Linux will be created to cater those who wish to learn from a separate operating system. To make sure that your Hugo was successfully installed and extracted, open your command prompt [Some ways in which this can be done => (Win key + r, type ‘cmd’, hit ‘enter’), (Go to your Search bar and the bottom of your taskbar and type in ‘cmd’ or ‘command prompt’ and hit ‘enter’)] and navigate to the directory where you extracted Hugo. For the above picture, my hugo.exe file’s location was D:\Hugo\bin\hugo.exe, so all I have to type is ‘cd D:\Hugo\bin’ and I will be taken to where the hugo.exe exists. If you’re not sure where you had saved your Hugo folder, you can either use the File Explorer you have presently open and simply highlight the path that is in the bar above your currently open Hugo folder. I have circled it below for your convenience.

file-location

To show what your command prompt should look like: hugo-location

Once you are here, feel free to try the command ‘hugo version’: hugo-version

If your command prompt happily prints out the current version of Hugo you have on your machine, this means you have successfully installed and extracted Hugo onto your machine. However, you may notice that if you use the command ‘cd ..’ to move directories to the ‘Hugo’ folder rather than ‘bin’ and try the command ‘hugo version’ you will be hit with an error or Windows will tell you that hugo isn’t a recognized command. hugo-error

If you are like me, and wish to be capable of using the hugo command anywhere on your machine, maybe because you would like to create a web page with its own folder and its own content, there is an easy way to fix this.

What you will have to do is navigate to your ‘Search’ bar and type in ‘env’ or ‘environment’. Windows will suggest the ‘Edit the System Environment Variables’. Open it and a System Properties dialog box should appear and look something like this: env-variables

Double-click on the button labeled ‘Environment Variables’ and this will open the dialog box where you can edit the environment variables of your machine. You may be wondering what environment variables are and what they’re for. In simplest terms, just like how you noticed that your hugo command did not work outside of the bin folder, there are other applications that work the same way and will only work in the folder they exist in. Windows has the capability of allowing you to run the application from anywhere, which is exactly what we would like to do. You should see something in your ‘user variables’ called Path. Each Path that is listed, is more than likely an application, similar to your Hugo, that exists only in a folder but is used globally on your machine. Highlight ‘Path’ and click ‘Edit…’. This will open a new dialog box that will list the individual paths that already exist. Click ‘New’ and simply type (or paste) the location of your hugo.exe. If you may recall from my example, my hugo.exe was in the following location; D:\hugo_ext\bin.

hugo-path-edit

Here’s what mine looks like after I have finished typing in where it exists (it is the one highlighted in blue). After you have done the same, you can now click ‘OK’ until all of the dialog boxes are closed. Now this is where the magic happens! After restarting your computer, try using the ‘hugo version’ command again outside of the ‘Hugo\bin’ folder and see if Windows recognizes it as a command! I simply started up my command prompt and immediately typed in ‘hugo version’ and it worked. If the command works, you are now ready to get started on a Hugo project.

Hugo-Version-Outside-Bin

Mac:

Installing Hugo on Mac:

The first step you will want to take is navigating to the website Homebrew. This website is a package manager and allows you to install, download and manage packages. You can use Homebrew to install Hugo easily on your computer. Once you are taken to the landing page, you should come across a terminal command that looks like:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

// NOTE: // This command may be updated depending on any new releases, // so be sure to check the website before copying the line of code above!

Simply paste the line of code into your terminal. Once you click enter and input your password for administrative access, Homebrew will begin installing itself onto your machine. This can take a few minutes. Once Homebrew is finished, you can then type the command:

brew install hugo

Homebrew may update itself automatically before installing hugo.

Determining if your Installation on Windows was successful:

You can validate your install by the command:

which hugo

You can also use the command:

hugo version

If you run into an error, proceed through the Windows steps and follow the instructions up until the GitHub section where you manually install the package from the repository for your own machine.

Creating a Hugo project:

Depending on your operating system, open your command prompt/terminal. You can also launch an IDE of your preference and have the terminal open within it. To create a new hugo project, be sure that you are within a directory that you would want to have your Hugo project created in. For this article, I will create a new folder within my D: drive (Windows) and then use the command:

hugo new site your_name_here

Refer to the steps within my command prompt below: I first check that my hugo command works, change directory into my D: drive, create a new folder called, ‘my_hugo_site’, navigate into that folder, and then create a new Hugo site called, ‘my_hugo_project’.

Hugo-New-Site

If you receive the ‘Congratulations!’ message, this means that you have successfully created a new Hugo site. If you expand the project folder to see its contents, you will see that a few folders have been created. (Be sure that you navigate within your newly created project first!)

Hugo-Project-Folders

The number of folders created here may seem a bit overwhelming, but have no fear! We will go over what each folder is for.

Archetypes:

The first folder is the ‘archetypes’ folder. This folder is typically used by those more confident with Hugo. An archetype, in its simplest form, is simply a constant that occurs throughout all of the content of your website, something that will not change. With Hugo, you can manually create data about your site (for you Computer Scientists, that’s metadata!). What this means is that you can assign values to things that will not be changing. This could mean, who initially created the website, what date it was created, what information populates the site itself, and etc.

Content:

A very self explanatory folder, this is where the main content of your site will exist.

Data:

You can almost view this as your website’s own database which can house .json files and allows you to utilize information that exists within external pieces.

Layouts:

Just like a word document, if you wish to add information within the same location of every page that exists on your website, such as a header or a footer, this is where you would add that.

Static:

This is, of course, where your static elements will exist. These elements may include your javascript or css files.

config.toml:

This file contains the settings of your website, such as its URL, what language it contains, and the title of the website.

Themes:

If graphic design isn’t one of your strengths, Hugo being an open-source project means that there are countless persons releasing their own themes and layouts for you to use! You can browse these themes here. Installing a theme is just as simple as downloading a folder to your machine, because that is exactly what you are doing! You may notice that every theme which peaks your interest will also exist on GitHub. You can use whatever method you prefer to retrieve the code. In this document, I will demonstrate a couple ways to do this. Once you find a theme that suits your needs or ‘aesthetic’, simply click on the theme. You may see two or three buttons, ‘Download’, ‘Demo’, ‘Homepage’. If you are confident that this is the theme you want, click ‘Download’ and it will take you to the GitHub repository where the theme exists. Click on the green ‘Code’ button and this will give you a few options on how to retrieve the code.

Git-Clone-Theme

For this example, I have found a theme that interests me titled ‘Dream’. For users who have Git, you can copy the https link and navigate into the ‘themes’ folder of your project to git clone it. Refer to the screenshot below (I am using Git Bash):

Git-Clone-Theme

When you clone the repository, it will automatically create a folder for you. However, if you are not sure how to use Git, you can simply download the Zip file onto your machine. Before installing this zip folder, be sure to create a folder within your ‘themes’ folder with the appropriate title of the theme you are downloading. After downloading the zip folder, you should extract the contents into the folder that you just created inside of your ‘themes’ folder. You can see in the screenshot below, that the folder ‘hugo-theme-dream’ exists within the ‘themes’ folder.

Theme-File-Location

After successfully implementing the above steps, navigate into your config.toml file and add the line of code below everything else that exists in the file:

theme = “folder_name_here”

So, in my case, I would type the following:

theme = “hugo-theme-dream”

After adding this line, save the document and to make sure that you have properly called this theme into your site use the following command in your command prompt/terminal to start up your Hugo local server:

hugo server -D

The -D will launch all of the draft pages that exist within your project folder.

After this, you can now open any web browser and type in the URL:

localhost:1313

You should now see your website and the theme you installed! From here, if you wish to contrbute, I recommend reading through our ‘Contributing to an Open-Source Project’ document!

Steps for Setting up our hugo dev site on your machine

  1. Since I have already created a fork of the atsign.dev repo, all I simply have to do is fetch the upstream for any recent changes made.

  2. I then proceed to git pull the updated forked repo (or if you haven’t already simply git clone it).

  3. You now need to edit the config.toml file so that your theme = “at_docsy”

  4. Get the https:// link from the at_docsy repo on our GitHub

  5. If you are using Git Bash all you have to do is navigate within the atsign.dev folder that contains the folders; content, archetypes, assets, etc. and use the command:

git submodule add "https://github.com/atsign-foundation/at_docsy.git" themes/at_docsy

This command will pull the at_docsy repo’s contents and add them to a created folder titled at_docsy under your themes folder

  1. Finally, use the command below and you will be ready to use the hugo commands:
git submodule update --init --recursive