Deployment

Deploying your project takes two steps:

  • Creating the software build
  • Creating and rolling out an image to the Cloud

While we aim for a fully automated process (including Continuous Integration), there are currently some semi-automated steps involved. This document will be updated constantly with the required steps.

Pre-conditions

Please make sure that you did not edit the environment.local to emulate the production environment (must not be env=prod but env=dev). Otherwise, the compile step will simply be skipped (do not compile in production).

It is important that you ran ant prepare globally before doing a deployment so that all dependencies in the platform are installed in correct versions.

Build Software

To build the software you need to perform the following steps:

  1. Boot your VM
  2. cd into your project directory (inside the VM)
  3. Run ant deploy (inside the VM)

The ant deploy command executes a full build chain which includes:

  • Ensure correct dependencies & versions
  • Run all tests
  • Performing code style updates
  • Eventually building the software (JS/CSS compile, minifying, chunking, etc.()

Please not that this will take some time.

Once the process has finished sucsessfully, you will find that the updated assets have been generated in the public/assets/.

You can now continue with Test the Build or directly commit & tag the build version for Rollout.

Test the Build

You can test the built assets by switching your local environment from development mode to production. This is done by setting

env=prod

in the environment.local file inside your project directory. This will make the base template source for the statically built assets instead of using the webpack dev-server. A reload in the browser will show you the result for inspection.

Please not to switch the environment back after testing.

Rollout

Once you are satisfied with the state of built assets, please commit them and tag the commit with the current date/time in the following format:

yyyy.mm.dd.hh.ii

You should use ant tag command that we provide, so that all required changes are done during the tag creation. For example, write the tag command, the current version number into the enironment config files etc.

$ cd ~/your-project-root
$ ant tag
Buildfile: /home/develop/your-project-root/build.xml

tag:
     [exec] [master b01f5032] Built release 2019.08.02.10.47
     [exec]  2 files changed, 56 insertions(+), 1 deletion(-)
     [exec]  create mode 100644 paas/catwalk/src/ant/tag.xml
     [exec] Aktueller Branch master ist auf dem neuesten Stand.
     [exec] To github.com:frontastic-developers/customer-project.git
     [exec]    1eb316cf..b01f5032  master -> master
     [exec] To github.com:frontastic-developers/customer-project.git
     [exec]  * [new tag]           2019.08.02.10.47 -> 2019.08.02.10.47

BUILD SUCCESSFUL
Total time: 8 seconds

This command creates the tag and pushes it directly to GitHub so that it is ready to deploy.

Deployment the Cloud way

Now that you have a software version that you are satisfied with, you can trigger a deployment. Currently the deployment part does not provide a fancy UI and must be done on the command line with curl or a similar tool.

To get the command, you should open the following URL:

https://<your-project>.frontastic.io/developer/deployment

at the bottom of the page you will find an example curl command with your current session id, similar to:

curl \
    -X POST \
    --cookie 'FCSESSID0815=c95914cb7a3ef945f56cd0053ab01234' \
    --header 'Content-Type: application/json' \
    -d '{"tag": "####.##.##.##.##"}' \
    'https://<your-project>.frontastic.io/api/deployment/schedule?environment=$env'

copy this command into your shell and replace ####.##.##.##.## with the concrete tag you created earlier and the $env with staging or prod depending on the environment you want to deploy to.

If you already have a Frontastic API-Token you can also use the token based approach instead of your current backstage session:

curl \
    -X POST \
    --header 'X-Frontastic-Api-Token: 8023dc50-17d4-4223-bc06-cfd923c5e642' \
    --header 'Content-Type: application/json' \
    -d '{"tag": "####.##.##.##.##"}' \
    'https://<your-project>.frontastic.io/api/deployment/schedule?environment=env'

Getting current deployment status

At the moment, the status information is very limited and there is a time frame of about five minutes of silence where we spin off new machines etc. But you can access the status for the deployment with the following command:

curl \
    -X POST \
    --header 'X-Frontastic-Api-Token: 8023dc50-17d4-4223-bc06-cfd923c5e642' \
    --header 'Content-Type: application/json' \
    -d '{"tag": "####.##.##.##.##"}' \
    'https://<your-project>.frontastic.io/api/deployment/status?environment=env'

Adding more and more status information to this service endpoint is currently a work in progress.