To run a database that can be used by the Ampersand prototype framework, you can easily use a Docker image from: docker.pkg.github.com/ampersandtarski/prototype-db/prototype-db

Prerequisites:

1. Make sure that ports 80 and 443 on your laptop are available. (In other words: if you run a web server on your laptop, bring it down.)

2. Make sure that docker is running on your laptop.

Here is what to do:

1. git clone https://github.com/AmpersandTarski/project-template into an empty directory, so you have all the necessary files needed to deploy your application. We will call this the working directory.

2. Substitute the file "MyScript.adl" in the working directory for the Ampersand script you want to run.

3. Edit the file .env to choose a root password for the database and an ampersand password for your application that accesses this database. Please choose safer passwords than the ones shown, which are merely examples. DON't publish the .env file once it contains your passwords. If you make your own repository, take care that your passwords do not accidentally appear on github.

4. Edit the file Dockerfile and substitute the filename "MyScript.adl" for the file name of your Ampersand script.

5. Open a command line interface (CLI) and navigate to this directory

6. Call "docker compose build". This step bakes your image. Docker stores that image on your laptop.

7. Call "docker network create proxy". The configuration uses a docker network called "proxy" to connect to ports 80 and 443 of your laptop, so you can use your browser to play with your application

8. Call "docker compose up -d". This instructs docker to deploy your application.

9. Go to your browser and navigate to localhost to access you application.

10. Press the red install button on your application to spin up the database under your application.

Now you are set to go and tinker with your application.

Things that can go wrong

to be done

To run the Ampersand compiler from any computer that runs docker, use a Docker image from our Ampersand repository on GitHub: docker.pkg.github.com/ampersandtarski/ampersand/ampersand

Make a shortcut tag to save typing:

Different tags are available, e.g.:

• :latest -> development branch It contains the most recent developments that have passed the automated test sets.

• :stable -> master branche This contains the latest stable release of ampersand. Use it for the lowest risk.

• :[branch] -> specific branch This allows you to pick a version yourself

• :v3.17 -> specific tags/releases To use a specific previous version.

This alternative presumes you have docker installed on your computer and it can be found (i.e. the path is set correctly).

If you experience problems downloading from docker.pkg.github.com, you may first have to log in with an appropriate token. Generate a token and be sure to switch on all repo-rights and the read:packages-right. With that token log in:

Different aspects of the Ampersand user's environment can be containerized 1. Ampersand compiler 1. Modelling environment for Ampersand user (incl. VSCode extensions) 1. Prototype environment, including:

• Apache webserver with PHP

• Ampersand compiler

• PHP-composer

• NPM (Node Package Manager)

• Gulp

  1. Multi-stage prototype build, only:

• Apache webserver with PHP

• Generated code

  1. Prototype database

• MariaDB with default user/password

A docker-compose file is available to deploy prototype, database and supporting tools (like phpMyAdmin)

Deploy your local environment to run Ampersand prototypes

Detailed technical instructions are at under the directory listing. This page provides more general and summarized information as context.

The contains a docker-compose and Dockerfile to generate, build and run a prototype application.

Run: docker-compose up -d to deploy the following services:

• Apache webserver

  • Serves your prototypes

  • Available in the browser at http://localhost:80

• phpMyAdmin dashboard

  • Available in the browser at http://localhost:8080

• MariaDB database

  • Not directly exposed on host

Install instructions for Windows

• Click on the green “Code” button and pull down to “Download ZIP”

• Download the zip and copy the directory on your laptop

• With a command line interface:

  • docker-compose up –d

  • you may need to enter “docker network create proxy” and repeat “docker-compose up –d”. The second time is a lot faster

• Go to the Docker desktop app

  • Find rap-master or the name you gave this docker app

  • Click the play button (the triangle)

• Go to “localhost” on your browser and RAP should be running there as it does on the course server

  • If that doesn’t work then to back to docker and stop and restart rap4 but enter “2020” as the port and go on the browser to “localhost:2020”