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

Return to the regular view of this page.

How to get started with the @platform

The fastest way to get started developing your privacy-first app on the @platform

The @platform was open-sourced in November of 2020 and we’ve been working hard to make your onboarding experience as smooth as possible ever since.

We’re excited to help you get your very own @platform environment up and running!

Prerequisites

You will need Flutter/Dart installed on your machine. If you haven’t already, please follow the “Get started” steps on flutter.dev before you proceed. Flutter works best with Android Studio, but you can also use IntelliJ or Visual Studio Code as your IDE.

Flutter

Why did we choose Flutter? Here are some of our favorite reasons:

• Beautiful User Interface that allows you to control every pixel in your app, bring your brand to life, and provide flawless People experiences.

• Apps directly compile to native ARM code for screaming fast and efficient project builds housing buttery-smooth animations that allow GPU acceleration.

• Hot Reload. Make an edit to your code and Flutter will update your source code files and automatically rebuild the widget tree, allowing you to see your edits almost immediately. No more rebuilding your application time and time again.

• It’s free and open-source, just like the rest of the @protocol, and there are countless numbers of packages on pub.dev that any developer is free to use. The Flutter community is growing fast and would love to welcome you!

Android Studio

Android Studio is an incredible Integrated Development Environment (IDE) you can use to create projects for Android devices, and to ease this process,it allows you set up an Android Virtual Device (or AVD). If you’re looking for an easy IDE to get started on, this is the one we recommend. Most of our code, documentation, and tutorials are created with Android Studio, so you’ll feel right at home!

Important Links for Android Studio

  • Download Android Studio here
  • Read an article on how to set up an AVD here

IntelliJ

IntelliJ is another commonly used IDE. It has a similar feel to Android Studio and is comparable to the other two IDE’s recommended here.

Important Links for IntelliJ

  • Download IntelliJ here

Visual Studio Code

Visual Studio Code, when compared to IntelliJ and Android Studio, is the most customizable with a seemingly endless number of programming languages to utilize. Developers commonly call this IDE ‘VS Code’ (who has time to say entire words anyway?). If you have watched our tutorials on atsign.dev, you’ll notice that VS Code is the other IDE of choice with our devs!

Important Links for Visual Studio Code

  • Download Visual Studio Code here

Docker Desktop

If you wish to develop offline, you will also need to install Docker Desktop on your machine. Using Docker Desktop allows you to run the full @platform stack locally, with no dependence on Internet connectivity, we call this the Virtual Environment.

Where should I go next?

There are three ways to get going with your journey on the @platform. You may choose any of the three options listed below depending on your interest and particular needs.

If you just want to get going and fast, then the best solution is to get some free @signs and start coding. Here we will show you how to get a couple of free @signs and activate them. This option uses The @ Companies infrastructure to host a secondary server microservice for each @sign you activate.

Dess (distributed edge secondary server) is the right place to start if you would like to run your own infrastructure, for your @sign. Or perhaps you are developing an IoT solution and would like to see the log files of the secondary server microservice, then using dess, is the perfect starting place.

(Option 3) The Virtual Environment

Recommended for those offline moments or if you want to be completely independent. The virtual environment (VE) provides all the components of the @platform in a single docker image. Complete with full control and logging of everything, VE requires no Internet connection and comes with some predefined @signs.



( Please note that all the logos listed on this page are registered trademarks of the respective products.We have used them here only for reference purposes.)

1 - Option 1 : Set up the @platform with free @signs

Create and run your own @platform with free @signs

Getting @signs and keys.

Your first step is to get a couple of @signs, it is best to get at least two, so you can experiment with sharing end-to-end encrypted data across the @platform.

There are two methods to get @signs.

The first

Go to atsign.com and clicking Get an @sign. If you go this route then you have more influence on your free @sign or pay for one of your choosing. Once you have your @signs, do not forget to activate them.

activate @sign

Activating creates a microservice (we call the secondary server) and once that is spun up on The @ Company infrastructure you will see a QR-Code to scan with an @ enabled application.

activated @sign

The pairing consists of your device creating cryptographic keys and sharing the public keys to the secondary server, you will be asked to store your private keys. Storing your keys is vitally important as only you have the keys.

The second

The experience of getting a @sign via the website is great for developers as you have advanced options available, to reset @signs and to point your @sign to your own infrastructure. For getting people onboarded quickly, a better experience would be to get a free @sign within the app itself, this is option 2.

generate @sign

The onboarding widget together with an API key provides a button marked “Generate Free @sign”.

generate @sign-pair

When selected a number of free @signs given to chose from, once selected it is quickly activated, then once again you will be asked to store the cryptographic keys for the @sign.

Once you have your @signs and keys

You are ready to start using the @platform! We have a number demo apps that are constantly being updated, feel free to fork or clone and try them. There is also another nice app in development by xavierchanth which is a chat app using the @platform. It is a nice example to follow as it uses the contacts combined with the at_chat_flutter widgets to create a simple chat app between @signs.

ChitCh@t

Each @ enabled application will ask you once for your @sign and then your keys, so it can synchronize with your secondary server. This means you might like to store your keys on a personal network drive or service (e.g. gdrive/idrive/onedrive) so you can connect other @ enabled apps to your @sign easily. Remember not to share and protect your keys.

Other widgets and the @platform/@protocol source code

We have an ever-growing number of widgets on pub.dev The @plaform and the @protocol are open source projects on GitHub. If you see something missing, or not working let us know or better still contribute with a PR!

2 - Option 2: Setup your own secondary server with dess

Create and run your own @platform secondary server with dess

1. What is dess?

dess is the self-hosted option for secondary servers, and a great tool for developers to debug their applications! You can run several secondary servers on a single instance of dess, as each secondary scales to use 6MB of ram or less.

dess is an acronymn for:

d. Distributed
e. Edge
s. Secondary
s. Server

2. How to get started

There are two parts to setting up dess:

  1. First time setup (run once)
  2. Setup an @‎sign (run for each @‎sign)

3. First Time Setup

Get a server

First get yourself a microserver to run dess on.

We recommend AWS, GCP, or IONOS for hosting.

1 Core + 1 GB is more than enough to run dess comfortably.

Install dess on the server

dess will install everything you need to get up and running.
Run the following command to install dess:

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

Alternatively, if you would like to save the installation script to your machine:

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

The script will be saved as getdess.sh

Setup a domain for your server

If you don’t have a domain available you will have to purchase one to continue.

Once you have a domain available, set an A record pointing to the IP of your server.

For example:

Domain: example.com
Server IP: 123.123.123.123

Example A record:

A    dess    123.123.123.123

You may replace “dess” with any valid value for a subdomain.
In this example, my fully qualified domain name (fqdn) is:

dess.example.com

Once you have completed these steps, please move on to setting up your secondary server!

4. Setup a secondary server

On my.atsign.com/dashboard

  1. Go to “My @‎signs.”
  2. Select “Manage” for the @‎sign you would like to setup.
  3. Open “Advanced Settings”.
  4. If the atsign is activated, follow the steps to reset it. (Warning: this will erase your data!)
  5. Under “settings” enter the fully qualified domain name from initial setup.
  6. Enter an unused port number.
  7. Press “Activate”

On your dess server

dess will show you the steps to setup a secondary server.

sudo dess-create
> Usage sudo dess-create <@‎sign> <fqdn> <port> <email> <service>
> Example sudo dess-create @‎bob bob.example.com 6464 bob@‎example.com bob

Arguments

@‎sign: The @‎sign you want to setup.

fqdn: Fully qualified domain name to use for dess.
(The same as entered in your atsign.com dashboard )

port: The port to use for dess.
(The same as entered in your atsign.com dashboard)

email: An email you own to sign the certificates with.

service: A name for the docker service.

5. OS Support

DistributionVersionx86arm64armv7
Amazon Linux2
Centos7,8
Debian10
Raspbian10
Rocky Linux8
Ubuntu20.04-21.04

6. dess Setup Guides

If you are ready to get started, please check to see if we have a specific guide available for your platform of choice.

We have guides available for the following platforms:

7. Tips & Tricks

Oops! I forgot to save my QR code!

Don’t worry! dess includes a command to recover QR codes.
Simply run the following:

dess-reshowqr <@‎sign>

Debugging Applications with Dess

dess runs as a docker swarm, to debug an application first run the following:

docker service ls

Docker will list the services running:

ID             NAME                   MODE         REPLICAS   IMAGE                          PORTS
b61ty3y5g41a   secondaries_shepherd   replicated   1/1        mazzolino/shepherd:latest
ex2d0kmiqinn   wolverine_secondary    replicated   0/1        atsigncompany/secondary:dess   *:6464->6464/tcp

For example, I have the service called “wolverine_secondary” running.
To debug this secondary using docker:

docker service logs -f <service_name>
# OR
docker service logs -f wolverine_secondary

While this is running, you will be able to see the secondary in action.

3 - Option 3 : Set up the @platform virtual environment

Create and run your own @platform virtual environment on your machine

Why is there a virtual environment to set up, and what does it do? Jumping directly into the deep end and creating projects on top of the @platform can be overwhelming, so we have made a simple way for you to run the @platform from your machine.

First, why is there a virtual environment to set up, and what does it do?

The virtual environment has two main benefits: you can monitor the status of your test secondary servers (by visiting localhost:9001), and you can bypass the traditional onboarding process completely.

Jumping directly into the deep-end and creating projects on top of the @platform can be overwhelming for some. To combat this overwhelming feeling, we have created a simple way to have you run the @protocol from your very own machine!

This will allow you to run both a root server and secondary servers of testable @signs. We have created demo apps that go over specific verbs and methods to help you get oriented.

Setup Virtual Environment

Windows

Your machine’s BIOS may already have virtualization enabled. You can check here.

Loopback adapter

Install the Microsoft loopback adapter and configure it. Here’s a video showing how:

Start up the at_virtual_environment

Run cmd and enter the following commands. You can run cmd by using the Windows key and the r key then typing cmd.

mkdir ve
cd ve
curl -L atsign.dev/curl/virtualenv-compose-vip.yaml -o docker-compose.yaml

Now you are ready to spin up the docker containers:

docker-compose up -d

Okay, you’re up. Now you can check the http://localhost:9001/.

Not sure what to do now? Try here!

MacOS

Configure Network Adapter

Open the Terminal window and enter this command. This permanently puts the Virtual IP address in place. You only need to run this once!

sudo curl -L atsign.dev/curl/atloop.plist -o /Library/LaunchDaemons/atloop.plist && \

Once you enter the above command, an arrow “>” should show up to enter the next line:

sudo launchctl load /Library/LaunchDaemons/atloop.plist

The command line may ask you to enter your password. Go ahead and fill it in if this happens.

Start up the Virtual Environment

Make a new directory called “ve” and run the curl command inside of it:

mkdir ve
cd ve
curl -L atsign.dev/curl/virtualenv-compose-vip.yaml -o docker-compose.yaml

Now you are ready to spin up the docker containers:

docker-compose up -d

Not sure what to do now? Try here!

Linux

Configure Network Adapter

Open the Terminal window and enter this command. This permanently puts the Virtual IP address in place. You only need to run this once!

curl -L atsign.dev/curl/rc.local -o setvip.sh
sudo ip addr add 10.64.64.64/32 dev lo
sudo nano /etc/rc.local

If the file “/etc/rc.local” is empty, then add the contents of the file “setvip.sh” to /etc/rc.local”. If rc.local already has content, then add the line “ip addr add 10.64.64.64/32 dev lo” above any lines that say “exit 0”. This will ensure that the virtual IP is in place even after a reboot. Ensure the permissions are correct with the following command:

sudo chmod 744 /etc/rc.local

Start up the Virtual Environment

Make a new directory called “ve” and run the curl command inside of it:

cd ~
mkdir ve
cd ve
curl -L atsign.dev/curl/virtualenv-compose-vip.yaml -o docker-compose.yaml

Now you are ready to spin up the docker containers:

docker-compose up -d

Okay, you’re up. Now you can check the http://localhost:9001/.

Not sure what to do now? Try here!

To Pull Latest Virtual Environment Version

docker-compose down
docker-compose pull
docker-compose up -d

Congratulations! You’ve set up your virtual environment and can now experiment with the hello_world app. Now you can start building your very own privacy-conscious apps.

When writing code, the only change needed to run in the virtual environment is changing the ROOT_DOMAIN to point to vip.ve.atsign.zone. The production value is root.atsign.org.

To Authenticate with Demo QR Codes

You will need the PKAM and CRAM Key QR codes in order to properly authenticate your testable atsigns.

You will find the group of these keys on our GitHub here

Where should I go next?

Give your users next steps from the Overview. For example:

  • Sample Apps: See apps that show off the power of the @platform on your own machine!

4 - Create your own @platform project

Taking one step closer to developing your privacy-first app on the @platform

If you’ve ever used Flutter and have gone through the process of creating a new Flutter Application Project, you’re more than likely aware of what a fresh application should look like. We’ve decided to create our own toolkit here on the @platform to make your ‘Getting Started’ experience that much smoother!

As of now, the only way to use this toolkit is via the command line. In the future we plan on supporting IDE extensions, be sure to check for when those come out!

Getting started via the command line

at_app is our command line toolkit that can be installed via pub. Behind the scenes, it uses flutter create in order to create your project, and it completes the necessary steps to setup your @platform application for you!

Install the command line toolkit

flutter pub global activate at_app

Verify your system PATH variable

  • When you run the command above, it may prompt you that the pub cache bin is missing from the system PATH variable.
  • The prompts will tell you the appropriate steps to add it to the PATH variable.
  • Please complete those steps before continuing.

Run the program

Note for Windows users

  • In the following commands you will see the at_app command, please replace it with at_app.bat.

Command Format

at_app create [...options] path/to/your/project

In practice the command looks like this:

at_app create --namespace=myatsign myproject

In addition to the same options available for flutter create, at_app create includes three new ones to help you automatically configure your application.

FlagShorthandDescriptionValue
-‎-namespace-nThe @protocol app namespace to use for the application.(defaults to “‎”)
-‎-root-domain-rThe @protocol root domain to use for the application.[prod (default), ve]
-‎-api-key-kThe api key for at_onboarding_flutter.(defaults to “‎”)

Note: at_app create does not include --template, --sample, or --list-samples (Coming soon).

Okay great, we know what the flags are but what do they do?

Namespace

The namespace is the most important flag to include when creating your application.

When storing keys on the secondary server, the namespace is used to filter the data produced by your app from the other @platform applications. To create a namespace for your app, make sure to register an @sign from atsign.com and use that as your namespace. By owning the @sign, you can ensure that you also own the namespace.

You can specify the namespace with --namespace=YOUR_NAMESPACE_HERE.

Root Domain

By default the root domain is set to prod (production). In the production domain, you can use real @signs to test your application.

Alternatively you can specify --root-domain=ve in the command to choose the virtual environment, and test with those @signs instead.

API Key

When you are ready to publish your application, you can request an api-key for the Onboarding Widget. This api-key will authorize your app when attempting to generate a free @sign within the widget.

You can specify this with --api-key=YOUR_API_KEY_HERE.

Updating your configuration

If you would like to update your environment at any point in time, it is safe to do so. Just specify the options you would like to change.

Warning

  • Do not use the --overwrite flag when doing so, or it will overwrite the changes you have made to lib/main.dart

Congratulations!

You have successfully created your first @platform application!

Time to start coding!

Where should I go next?

We recommend checking out the demo apps that we have to offer! Reviewing these will greatly assist in your understanding of verb implementation on the @platform! It would also be a good idea to check out our @dev program which will show you how to have your app @certified and released to the market!

  • Sample Apps: See apps that show off the power of the @platform on your own machine!

  • @dev Program: Read up on how to get your @certification and go to market with your privacy-focused application!