Ampersand is great for rapid prototyping. We advise you to do that on the web. But sometimes you want to run your prototypes on your own computer(s). For different purposes there are different ways of doing that. This chapter shows you how.
You can use any text editor to create Ampersand scripts. However, for those that use the Visual Studio Code (vscode) editor, there is language support. All you have to do is search for the vscode extension "Ampersand (ADL) language support" and install it, and then choose the coloring theme called "Ampersand".
Using Ampersand offline does not require you to install Ampersand. Ampersand runs in Docker so you can use it independently and on almost any platform. Here is an explanation of how to do this (don't mind the title of that page). It can be summarized as follows:
Make sure Docker runs on your laptop or install it if it doesn't.
Copy the files Dockerfile
and docker-compose.yml
and adapt them for your own Ampersand prototype. Read this if you don't know where to find them.
Run your .adl
-file on the Docker platform.
DIY-engineers will find instructions in section Installing the tools manually. You need a webserver that can run javascript, PHP7, the PHP composer, and a (My)SQL or MariaDB database server. For generating functional specifications, you might use LaTeX, Markdown, Word .docx and other formats. This chapter gives an overview of the Ampersand production line for whoever needs to circumvent the automated process.
RAP4 is an Ampersand repository, in which multiple users can store and use their Ampersand scripts. Consult the tools we use at Ampersand. This is work in progress.
If you want to change the Ampersand compiler for your own purposes, you need access to the source files, and a Haskell development environment. This section still has to be written. It will describe the software process for developing Ampersand itself.
The remainder of this chapter explains in detail all the things you need to get you up and running with Ampersand. The instructions presume that you are familiar with your own computers.
How do you get started if you just want to build and run your first prototype? Read this page, which is full of hyperlinks to background knowledge you will need in the future if you deploy more often.
We use a docker-platform to run your Ampersand program on virtually any computer. So go ahead and install docker if you don't already have it. You provide (once) a recipe for building (Dockerfile) and a description of the configuration (docker-compose.yml). We'll provide examples for you to adapt.
Your Ampersand prototype will run in a container, which is a virtual machine.
The container is started and stopped by docker-compose
, which uses a docker-image
that is built with your Dockerfile and deployed with your docker-compose.yml file.
Run your image from your command-line, using the command docker-compose up -d
. You can verify that it runs with docker ps
.
Access your application through your browser, using <TODO: Which URL?>
Please watch this video (8 minutes) to see what Docker does to bring up your Ampersand program as a web application on your own machine.
You need a computer that runs Docker and that has an internet connection. That lets you generate a Docker image from your Ampersand source code. Then run your program on Docker on localhost.
First, you create a directory in which you will organize your Ampersand (.adl) files and some other stuff. We will refer to this directory as your working directory. In this working directory, make sure you have:
A file called Dockerfile
, which contains the recipe for creating a Docker image
A file called docker-compose.yml
, which contains the runtime configuration of the containers running your program.
The source code of your Ampersand program, as specified in Dockerfile
and docker-compose.yml.
Then from you command line interface run:
docker-compose up -d
Sit back and watch. Don't worry, the second time around Docker downloads much less as it builds up its local image repository.
The deployment consists of the following steps:
Copy your .adl
-file to a working directory on your server.
Get two docker-files from internet by executing the following commands:
On servers other than Linux, you may need another command than wget
, but the files are the same.
In the file called
docker-compose.yml
you must specify your own
.adl
-file:
Run docker-compose to deploy your prototype by executing the following command:
Alternatively, if you want your prototype to keep running after you have closed your CLI, execute:
Browse to the web-location my.server.com
, where the prototype is being served.
After you deploy the first time, you may want to edit your program. Just save the results and redeploy with the command:
If you want to see which images are stored on your local computer, type
Check if there is a firewall that blocks the port from internet. Make sure that port 80 is open for http-traffic.
Check the port settings and adapt docker-compose.yml
if you must use a port other than port 80.
Use a recent browser. We have developed Ampersand on FireFox and tested it on FireFox and Chrome, so you should be fine with one of these two.
If you have trouble with the database (e.g. you cannot login, or do not have the correct authorization), check out the instructions for creating a properly authorized user ampersand
for the database. As you can see in docker-compose.yml
, the database itself is accessible through port 8080.
It is a good idea to deploy your webapplication to localhost for testing. However, if you use a subdomain (e.g. my.ampersand.app.localhost) you will find that your hosts
-file does not support wildcard redirection. You can do this by installing a local dns server (details on http://passingcuriosity.com/2013/dnsmasq-dev-osx/)
Please make sure you have a good reason to do this manually. Using the automated procedures is much easier...
All graphical output is created using GraphViz. You need to install it. Make sure dot and neato are in your path (set the $PATH environment variable if necessary). Also, if you compile it from source, make sure you install it with gts support.
There are several formats that you can generate a functional specification document in. Currently, the best results can be obtained in docx or LaTeX (PDF). Depending on your taste, you need appropriate software:
For docx, you could of course use Microsoft Word, but there are other options as well.
Ampersand models are written as source code files. Hence, you need a text editor in which you can do so. We recomend Visual Studio Code, which has a nice extention for Ampersand scripts. You could however use any text editor that you are familiar with, as long as you make sure it saves files as UTF8 format.
The following instructions presume that you are familiar with the basics of your own computer.
The easiest way is by use of available executables. We release frequently. Have a look at our latest release. For Windows users, there is a file called ampersand.exe in the release. Put it on your disk on a location of your choice, for example /Ampersand/bin/. Make sure your $PATH
(or: PATH
) environment variable contains this location, so the command "ampersand" is known on the command line. That's all. Note that double-clickingampersand.exe
will not work, because it is a command line tool.
Here is a way to test whether or not you have succeeded: open a command line tool (e.g. CMD
on Windows), and type ampersand -v
. If all is well, the version number of the Ampersand tool is output.
Now you can compile and check your Ampersand scripts. However, you are likely to want to do more with such scripts. Currently it is possible to generate functional specifications and/or functional prototypes from such scrips. You will need to install some additional software in order to do that.
If you want to generate functional specifications from ampersand scripts, you need the following additional software (if you don't, don't bother installing them):
All graphical output is created using GraphViz. You need to install it. Make sure dot and neato are in your path (set the $PATH environment variable if necessary). Also, if you compile it from source, make sure you install it with gts support.
If you want to generate functional prototypes from ampersand scripts, you need the following additional software (if you don't, don't bother installing them):
In order to run the generated prototype, you need Apache (or another web server) with SQL and PHP v 7.1 or higher. In Windows, a practical way is to install XAMPP
You must create an account in SQL for
localhost
, that has a user called
ampersand
with a password
ampersand
, with rights to create/read/update/delete databases as well as their contents. If you use phpmyadmin this could look like:
The webserver must run on localhost
. By default you will use port 80, but you could change that if required. See the documentation of you webserver.
You will also need to install Composer, because at runtime, the prototype has dependencies of libraries . Composer will take care of that.
If there is no executable for your operating system, or if you prefer to build an Ampersand compiler yourself, follow these steps:
Install stack, the haskell tool stack. instructions are here
Open a command line terminal, and go to the directory that contains the file named
ampersand.cabal
Then, close your command line terminal and reopen another one (this helps to reload the environment variables that the
stack
installation may have added or modified),Let
stack
install everything you need to compile (see the Notes below!) by executing:
$ stack setup
Build the Ampersand.exe file (see the Notes below!) by executing:
$ stack install
This will build an Ampersand-compiler named "ampersand.exe" and install it into your path.
Testing your installation
Open a command prompt.
Type "Ampersand --version". The expected behaviour is that Ampersand replies with the version of Ampersand. It will look something like:
The version number is important to specify, whenever you have a question of like to report an issue. It really helps us when you add the version number, including everything between the brackets when you contact us.
Ampersand allows you to generate a working prototype of your ampersand model. An Ampersand prototype is a website that requires a webserver to run on and a (My)SQL database server. This chapter describes the prerequisites for getting such prototypes up, and running.
First, you should get a working script. Let's assume it is called myModel.adl
and it contains valid content such as is shown here below:
Don't worry if you do not understand what everything in this script means. That isn't important for now.
If you do not have such a script, you can copy the above text, paste it in a text editor and save it. Different novice users have shown that this may present some problems. One is that in some browsers (e.g. IE), copying the text will include the line numbers. If you see your file has line numbers embedded in the text, you should get rid of them before saving it. Another one is that it may contain characters that are not displayable in the editor - some editors will turn such characters into printable ones, e.g. a question mark. If that's the case with you, you should also get rid of them. You should end up with text in a file that is as is shown above.
Then, you can generate the prototype website for the script in file myModel.adl
by typing the command:
This creates a directory myModel.proto
(in the current directory), that contains the prototype website. Obviously, you will need a web server and a database server to run the prototype. This is discussed at Installing Ampersand.
Usually, you would have some demands regarding particulars of the generation. For example, you may want to generate the website in a specific directory, specify a particular CSS file for this website, etc. For the complete syntax of the Ampersand executable, see the chapter about the command line interface****
Notes:
1. Do not use Hackage to get ampersand. It does not contain all non-haskell files. (See issue #213)
2. stack
memory usage may require other applications to be terminated (e.g. on 8GB Windows systems). If stack
terminates prematurely, re-invoking the command will pick-up where it stopped.
3. stack
may terminate on various errors (See this issue), e.g. that it doesn't have permission to access or rename files. Again, if stack
terminates prematurely, re-invoking the command will pick-up where it stopped. Users have mentioned having to restart stack
several times before it would finally complete building Ampersand.exe.