See the links at the bottom of this page for independant system install directions.
The docker image is intended to be a complete standalone instance of the core application. There is no need to install Nginx, Apache or a DB on the host system. For instance this docker image will easily run on amazon/ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-20220912.
$ sudo apt update
$ sudo apt install ca-certificates curl gnupg lsb-release
$ sudo mkdir -p /etc/apt/keyrings
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
$ echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
$ sudo apt update
$ sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin
This command downloads a test image and runs it in a container. When the container runs, it prints a message and exits.
$ sudo service docker start
$ sudo docker run hello-world
Ideally, you should be using a brebones server. However, if it has a running instance of Nginx or Apapche, these should be disabled or removed.
If you do not have "paid-for" certificates, you can generate certificates that are not self-signed for free using certbot, provided by the LetsEncrypt foundation.
Install Certbot:
$ sudo snap install core; sudo snap refresh core
$ sudo snap install --classic certbot
$ sudo ln -s /snap/bin/certbot /usr/bin/certbot
Generate the certificate. Replace my.domain.com with your API domain name.
$ sudo certbot certonly --standalone --preferred-challenges http -d my.domain.com
List the certificates and their locations, and make a note of their locations for use when starting the image.
$ sudo certbot certificates
The ApiOpenStudio database data will be stored in a secure docker volume.
$ sudo docker volume create dbdata
The database and ApiOpenStudio images communicate with each other over a custom network.
$ sudo docker network create api_network
Replace the sample values of the MYSQL_USER, MYSQL_PASSWORD and MYSQL_ROOT_PASSWORD with your own, for security.
$ sudo docker run -d --name=apiopenstudio-db \
-e MYSQL_DATABASE=apiopenstudio \
-e MYSQL_USER=apiopenstudio \
-e MYSQL_PASSWORD=my_s3cr3t \
-e MYSQL_ROOT_PASSWORD=my_s3cr3t \
-h apiopenstudio-db \
-v dbdata:/var/lib/mysql \
--restart=unless-stopped \
--network=api_network \
mariadb:latest
$ sudo mkdir -p /data/apiopenstudio
$ sudo curl https://raw.githubusercontent.com/naala89/apiopenstudio/master/example.docker.settings.yml -o /data/apiopenstudio/settings.yml
Update:
db.root_password - same as MYSQL_PASSWORD in the create database container commanddb.username - same as MYSQL_USER in the create database container commanddb.password - same as MYSQL_PASSWORD in the create database container commanddb.database - same as MYSQL_DATABASE in the create database container commandapi.url - the domain for your APIapi.jwt_issuer - the domain for your APIapi.jwt_permitted_for - the domain for your APIemail.from - admin_username <email_address>email.reply_to - admin_username <email_address>Replace the paths for the certificate key and certificate, and apiopenstudio image tag that you want to install. Note: It is not advisable to use the latest tag, because this tag may be associated with the latest, potentially unstable develop or master branches - Select tags that that are release tags from the official site - i.e. 1.0.0-beta3. To find the latest image, visit https://hub.docker.com/repository/docker/naala89/apiopenstudio/general.
$ sudo docker run -d --name apiopenstudio-api \
-p 80:80 \
-p 443:443 \
--mount type=bind,source=/data/apiopenstudio/settings.yml,target=/var/www/html/settings.yml \
--mount type=bind,source=/etc/letsencrypt/live/my.domain.com/fullchain.pem,target=/etc/nginx/certs/apiopenstudio.crt \
--mount type=bind,source=/etc/letsencrypt/live/my.domain.com/privkey.pem,target=/etc/nginx/certs/apiopenstudio.key \
--network=api_network \
--restart=unless-stopped \
naala89/apiopenstudio:tag
With everything now running, we need to SSH into the api container and run the installation script to install the composer dependencies ans set up the database.
$ sudo docker exec -it apiopenstudio-api bash
$ ./install.sh
Continuing will create a new database and erase the current database, if it exists, continue [Y/n]:
y
...
Include test users and accounts [y/N]:
n
...
Enter the admin users username:
<my_admin_username>
Enter the admin users password:
<my_admin_password>
Enter the admin users email:
<my_admin_password>
...
Automatically generate public/private keys for JWT (WARNING, this will overwrite any existing keys at the location defined in settings.yml) [Y/n]:
y
...
ApiOpenStudio is successfully installed!
You will now be able to configure and use the admin GUI and/or make REST calls to Api OpenStudio.
Ensure that the API is running, fetch a logged in JWT token. Make a rest call with the following parameters:
This should result in:
{
"result": "ok",
"data": {
"token": "<long_token_string>",
"uid": 1,
"expires": "<timestamp>"
}
}