IxDF Developer Docs

Appearance

How to deploy ​

Our release flow is fully automated using GitHub API and CI/CD service. You can rely on it or in rare cases, you can use a Manual deployment.

Make sure you read After deployment checklist before releasing for the first time.

How to trigger deployment ​

Create a new Release on GitHub ​

Just create a new release on GitHub – it will start a full CI/CD cycle (with running tests and other checks). Release Drafter bot should've already created a release draft based on merged PRs (it usually requires 25sec after PR merge to update/create Release draft). In case you can't find a draft: Check if you have added proper release labels to your PR (pr-category:X and pr-size:X).

  1. If yes, then wait for a few seconds and refresh the page.
  2. If no, then you should create a release manually.

Note: You should always add relevant labels to your PR so that the release drafter bot can draft a release for you.

Release notes ​

Release Drafter bot will create a draft release note based on PR titles and labels (that’s why PR titles are important). Feel free to update the notes if needed. Make sure you check the changelog before releasing to make sure we don't miss any important changes.

In case you find any changes without a proper release note, you can either add them manually or ask the author to add them.

When you write release notes, please remember to use a language that's easy to understand by non-technical people. Anything technical should be marked by ⚙️ emoji or moved to the "⚙️ Internal changes" section (example).

Change categories we use:

  • ⭐️ Features
  • 🐞 Fixes
  • ✨ Improvements
  • ⚙️ Internal changes
  • 🧹 Removals

(release drafter will add them automatically based on your merged PR labels)

Manual ​

You can use the Deployer tool manually in the same way as it used on our CD/CI. Deployer is a PHP tool that can run different tasks on local and remote servers. In our case you need to know two commands: deploy and rollback. There are more Deployer tasks, you can find them in deploy.php file (task declaration looks like task(...)).

Deployer installation

In this doc we assume you have both PHP and deployer.phar installed locally. If you have PHP and Composer installed locally (what is recommended), you can install Deployer by running composer deployer:install). If, for any reason, you don't have locally installed PHP, you can:

  1. use an official Docker image: docker run --rm -it -v .:/app deployphp/deployer {task} {server}
  2. use PHP from the Docker Compose: docker compose exec app ./deployer.phar {task} {server}

Note, the majority of Deployer tasks require an SSH connection to the remote server, so you need to mount your SSH keys to the Docker container: docker run --rm -it -v ~/.ssh/id_rsa:/root/.ssh/id_rsa:ro -v ~/.ssh/known_hosts:/root/.ssh/known_hosts:ro .:/app:ro deployphp/deployer {task} {server} where id_rsa is your private SSH key and known_hosts is your known hosts file.

The most common cases when we use manual deployments:

  • deploy your working git branch to staging or test servers. Example: ./deployer.phar deploy staging
  • deploy urgent fixes to production when we don't have a time to wait for test and other checks

Ensure you use the latest stable version of Deployer:

bash
composer deployer:install

It will simply download a .phar file that you can use on the next step:

bash
# Deploy to staging app instance:
./deployer.phar deploy staging

TIP

⚠️ Note, deploy task will ship your git HEAD (current git branch and commit), remember to switch the correct branch before calling it.

Deployer uses SSH connection to run commands on a remote server. That means, before you use it, you need to add your public SSH key to a server you want to use for deployment.

There are some other convenient commands that you can run using Deployer, please check deploy.php for details.

Deployment rollback ​

In rare cases, new releases can contain issues like 500 errors or broken functionality. In such cases, you need to rollback it to use previous deployed release.

Rollback on production example:

bash
./deployer.phar rollback production

Under the hood it just changes a symlink and restarts some services, so it’s a way faster than deploy command.

Rollback (alternative way) ​

In case of issues with SSH access to production server, you can use GitHub action to run deployment rollback.

But this is just a fallback: it’s slower than the main way and thus not preferable.