Getting Started

Take a look at the Reference Guide for an overview of the bits, pieces and commands used throughout this tutorial.

In this tutorial we’ll take you through the steps going from a blank model to a small application.


To get you up and running we’ve created a project template. The build system we’re going to use expects a layout with files and folders in a particular structure, and this template sets you right on track for anything but the most complicated things you can build with Alan (like connecting to external databases).
So, download or fork and clone that template to get started.

Several steps involve entering commands on a Unix-like command line. Use whatever you like on Linux or macOS (as long you’ve got bash). On Windows you can use WSL or Git Bash via Git For Windows, as long as you don’t mix the two.

On Linux and macOS you can run the server and connect to it via the command line. In this tutorial we’ll use a virtual machine and a desktop application, which should work for everyone.

Project Layout

You’ll notice some top level directories here.

For now, you can ignore deployments, migrations, systems and wiring. We’ll touch on some of those later, but we’ve got defaults set up there that will work for most basic projects.

First, lets take a look at the application model, as for most projects you’ll spend most time editing this file.

Application Model

Open the interfaces/model/application.alan file in an editor. We’ll be using Sublime Text in the screenshots, but you can use whatever you like.

The template already has a little model set up that covers some basics. Let’s walk through it before we wipe it clean and start our own.

The model is a nested structure not unlike JSON. At the first level you’ll see some keywords:

So, in root, you describe the data model of your application. You do so by combining properties of certain types. Essentially there are 5 data types in Alan:

There is a fifth type called group, which is just a construct to create grouping and name spaces: groups don’t actually hold any data by themselves.

Run It

Let’s quickly try to actually boot up this example project, before we go back to making our own application.

The workflow here is that you’ve got a server running somewhere (on your system, on the local network, or in the cloud) and you upload your application to it. The server then runs the application and you can use it via your webbrowser.

Get the server

Double click the Alan.ova appliance package to import it into VirtualBox. It has all the configuration already set up to Just Work™. Then hit the green Start button. When it’s done going through the boot sequence it will report the IP address (probably 192.168.xx.xx) and port number (probably 8888) you can use to connect to it.

Connect to the server

Build It

Let’s get ready to send the application to the server. The project holds the source code, but it needs to be compiled before the server can use it. There are a few step to this:

Tip: Run ./alan --help for a breakdown of what these commands do.

This results in a default.image file in the dist folder (all output is put in the dist folder by default). You can drag that file to the Alan Connect application and it’ll upload it to the server. Once that’s done you’ll see the application listed and you can hit the green “Start” button to start it. 🍾!

You can now open a browser and go to the ip address of the server, followed by the port the client is available on (it’s not the 8888 we just used to connect to the server). For this template it’ll look like this:

http://192.168.xx.xx:7584

Your own application model

While getting an application for free is nice, it’s even nicer to build your own. For that, lets start by wiping the application.alan file and then start over with this:

users
	dynamic :  . 'Users'
	password : . 'Password'

interfaces

root {

}

numerical-types

This clean slate for an application that has “users” and requires logging in.

Add users

Now let’s add those users to the model:

root {
	'Users': collection { }
}

We specified that for each user we store their password in the 'Password'property, so let’s add that too:

root {
	'Users': collection {
		'Password': text
	}
}

So, we’ve defined a ‘Users’ collection, where each key in the collection will serve as the “username” and there is a password they’ll need to provide to log in. The default user interface will pick this up and present the login form next time you run the application.

Add some collections

That should work, but our app lacks purpose right now. Why not build a little multi-user todo app (when not sure what to do, make a todo app right?). So, let’s say our users are involved in projects and each project has stuff that needs to be done.

root {
	'Users': collection {
		'Password': text
	}
	'Projects': collection {
		'Todos': collection { }
	}
}

We should probably have a little more information for each todo, like when it was created, or to which user it was assigned. It probably doesn’t hurt to be able to write down some details about the todo either.

'Todos': collection {
	'Created': natural 'date and time'
	'Description': text
	'Assignee': text -> .^ .^ .'Users'
}

Now we’ve already done some things I need to explain. Let’s take them one by one.

Numbers

'Created': natural 'date and time'

This creates a number property, typically a “natural”: meaning it can’t be zero or negative, which won’t make sense for a timestamp. We also give it the type of ‘date and time’. Properties that are the same kind of number (a “date”, or “kilograms”, or “minutes”) all have the same numerical type. This makes sure that when you’re making calculations, you also end up with the correct numerical type for the result value. More on that later, right now you need to register that numerical type:

numerical-types
	'date and time'

To help the user interface interpret this and serve up a nice date-time picker, we need to annotate this.

numerical-types
	'date and time' @date-time

References

The other thing that’s special here is the ‘Assignee’.

'Assignee': text -> .^ .^ .'Users'

It’s a text property, but we want it to refer to one of the users of the application. Let’s break down the syntax here:

Compiling

To verify that our new model is correct, let’s try to compile it:

./alan build

This fails because the client application is still configured to allow anonymous users, and we’ve just created an application that requires users to log in. Luckily the compiler tells us where to go to fix this.

If that’s successful we’re almost ready to run it. To do so, we first need to update our initial data definition by modifying the files in migrations/from_zero. Luckily, we have a script to do this for us:

./.alan/dataenv/system-types/datastore/scripts/generate_migration.sh migrations/from_zero systems/server/model.lib.link --bootstrap

We can then continue with the same steps as before:

In the Alan Connect app you can stop and delete the old application, and then upload and start this one.

When you refresh the browser, you’re now greeted with the login screen. You can log in as user “root” with password “welcome”, and 🎉 there is your application!

Next steps

The project template has an model filled with examples that cover what we call derivations: ways to do math with numbers or derive state groups from other data.

You can annotate your model to set default values and number formats. Check the model language docs for more details.

Migrations can be edited by hand, for instance to bootstrap your application with more data than is automatically generated. Learn more about it in the migrations tutorial.

If you want to learn more, check our documentation or ask on the forums!