renehernandez / appfile

Deploy App specs to DigitalOcean App Platform

appfile

Deploy App Specs to DigitalOcean App Platform

About

appfile is a declarative spec for deploying apps to the DigitalOcean App Platform. It lets you:

• Keep a directory of app spec values files and maintain changes in version control
• Apply CI/CD to configuration changes
• Visualize a diff of the changes to be applied
• See the status of your app

Installation

appfile can be installed in several ways.

Homebrew

You can install directly using the renehernandez/taps as follows:

$ brew install renehernandez/taps/appfile

Download releases

You can always download the released binaries directly from the Github Releases page. For the latest releases check here

Github Action

You can leverage appfile with your Github Actions workflows, by using action-appfile:

• Marketplace: https://github.com/marketplace/actions/github-action-for-appfile-cli
• Repository URL: https://github.com/renehernandez/action-appfile

Getting Started

Let's look at an example and see how appfile can help you to manage your App specification and deployments.

Deploy a web service

This example deploys an App containing a service definition. The 2 environments: review and production will customize the final specification of the app to be deployed. Let's look at the appfile.yaml, app.yaml and environments definitions below.

# appfile.yaml
environments:
  review:
  - ./envs/review.yaml
  production:
  - ./envs/production.yaml

specs:
- ./app.yaml

# app.yaml
name: {{ .Values.name }}

services:
- name: web
  github:
    repo: <repo-url>
    branch: main
    deploy_on_push: {{ .Values.deploy_on_push }}
  envs:
  - key: WEBSITE_NAME
    value: {{ requiredEnv "WEBSITE_NAME" }}

# review.yaml
name: sample-review

deploy_on_push: true

# production.yaml
name: sample-production

deploy_on_push: false

You can deploy your App in review by running:

WEBSITE_NAME='Appfile Review' appfile sync --file /path/to/appfile.yaml --environment review

The final App spec to be synced to DigitalOcean would be:

name: sample-review

services:
- name: web
  github:
    repo: <repo-url>
    branch: main
    deploy_on_push: true
  routes:
  - path: /
  envs:
  - key: WEBSITE_NAME
    value: Appfile Review

Or you can deploy your App in production:

WEBSITE_NAME='Appfile Prod' appfile sync --file /path/to/appfile.yaml --environment production

The final App spec to be synced to DigitalOcean would be:

name: sample-production

services:
- name: web
  github:
    repo: <repo-url>
    branch: main
    deploy_on_push: false
  routes:
  - path: /
  envs:
  - key: WEBSITE_NAME
    value: Appfile Prod

To learn more about appfile, check out the docs

Contributing

Check out the Contributing page.

Changelog

For inspecting the changes and tag releases, check the Changelog page

Appreciation

This project is inspired in helmfile, from which I have borrowed heavily for the first iteration.

License

Check out the LICENSE for details.

appfile's Issues

Expand job section coverage as part of the lint command

Fields that need to be added:

• kind

Print hostname when app is deployed

If the app specification declares any domains:

# app.yaml
domains:
- domain: example.com
   ...

then the execution of appfile sync -f /path/to/appfile should output a log message showing the URL where the app will be accessible.

This is specially useful when the domains are dynamically generated based on the environment used by appfile

Expand lint command to support domains section

It needs to validate the following fields:

• domain
• type

Add chocolatey package

Support reading environment variables from a .env file

Instead of having to specify the environments variables as part of the CLI invocation or export them in the session, it would be convenient to load them from .env file. This improves the user experience when manually running appfile

New option to add to the root appfile command:

--env-file: Pointing to the path of the env file to load

Add list command

The list command should allow to list all the defined apps in a given appfile.yaml specification.
List all apps in an appfile:

appfile -f /path/to/appfile.yaml -e <env> list

Invalid trailing character when trimming name field to 32 chars

Using the name portfolio-snippet-alpine-python-image, it will be trimmed to portfolio-snippet-alpine-python-, which is incompatible with the regex pattern used by the DigitalOcean API

Add logs command

New command to be able to see logs from the deployed applications. Example invocations:

appfile logs <app_name> -e <env> -f </path/to/appfile.yaml 

appfile logs <app_name> --component <component name> -e <env> -f </path/to/appfile.yaml>

Flags:

• Support for -t/--tail option to follow the logs live
• Support selecting the type of logs to show (build, deploy, run). Should default to run

Expand lint to cover global envs array section

It needs to validate the following fields:

• key
• scope
• type

Delete CNAME on app file destroy

If there is a domain defined in in the app.yaml spec linked to a DigitalOcean DNS-managed zone, it automatically adds a CNAME on app creation, but doesn't remove it when the App is destroyed.

Appfile should check during the destroy operation if there is a domain specified and delete it using the godo sdk

Add a rollback command

This command would allow to revert the application to a previous deployment id. The command would support two modes.

Rollback to the previous deployment:

appfile -f /path/to/appfile -e <env> rollback <app_name>

Rollback to a specific previous deployment id:

appfile -f /path/to/appfile -e <env> rollback <app_name> <deployment id>

Expand services coverage as part of `lint` command

New fields to process:

• health_check (valid integers)
• cors
• routes
• routes cannot be set if internal_ports are set

Redirect to latest documentation

Currently, the redirect is hardcoded to latest version at the moment (v0.0.5). This should be updated as part of the release process to point to the newer version

Expand static sites section coverage in `lint` command

New fields to cover:

• catchall_document or error_document only one can be present
• routes
• cors

Publish documentation

Replace list command with status command

The current list command implies that is about listing different app specification, when what it can be done is provide status about the current deployment.

So, the list command should be replaced with a new status command which should cover the following:

global information

• name
• updated
• status
• deployment id
• default url

Add Github Action for appfile

Read directly app.yaml

To ease new users of appfile, it would be interesting to support reading directly from the app.yaml spec file. From an execution viewpoint, this would be similar to an appfile.yaml declaring just one spec and no environments.

Add support for blocking `sync`

For CI systems it would be useful to have the option of appfile not retuning until the application has been fully built and deployed, with a non-zero exit code if something goes wrong.

Digital Ocean has added a similar --wait flag to doctl.

Add homebrew formulae

Expand lint support for databases section

It needs to validate the following fields:

• name
• engine

Add E2E tests against DigitalOcean

As the number of features start to increase, and complexity as well, it is important to verify that behavior at the system level is not affected.

E2E tests should cover execution of commands against known outputs

Add lint command

Would allow to validate the final app.yaml spec against a known set of rules. Specially useful to run as part of the CI/CD pipeline to avoid triggering a deployment with an invalid configuration

Command:

appfile -e <env_name> -f </path/to/appfile> lint

NOTE: To implement this, I have to wait for digitalocean/godo#422

Add capabilities to pull app spec from remote url

This would be a great extension to the current appfile capabilities. It would be nice if it could behave similar to what helm does with repos and pulling charts from remote.

Stable repo

Ideally, there would be a stable repo, that could host community-maintained app specifications. In addition, the implementation could support (at least having this in mind for the first iteration) adding custom repos, so that orgs could have their own private repos.

Note: Appfile would ship with the stable repo by default

Implementation

The appfile specification would need to be modified to support the new releases block instead of the old specs block

appfile spec overview

environments:
  review:
    - ..
  production:
    - ..

releases:
  - name: my-ghost # could be optional
    spec: stable/ghost
    values:
      - values.yaml
  ...

Repo commands

appfile repo add <http_url>

appfile repo list

appfile repo delete

appfile repo update

Limitations

• Spec published in the stable repo need to use a container image with public access. Of course the image field itself could be overwritten to point towards any internal/private container registry

Configure CI for release

• Produce release artifacts for the supported os/arch
• Generate github release