Deploying an Backend App on Dokku

This guide provides detailed instructions on how to deploy an backend app on Muyan Dokku PAAS Platform.

Deployment Steps

Creating a New Backend Application on Dokku:

• Log into your Dokku host using the command ssh root@your-dokku-host.
• Create a new app using the command dokku apps:create samt-server.

Adding a PostgreSQL Plugin:

• (Not required on Muyan PaaS platform) Add the PostgreSQL plugin using the command dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres.
• Create a new PostgreSQL service using the command dokku postgres:create samt_postgres.
• Link the PostgreSQL service to your app using the command dokku postgres:link samt_postgres samt-server.

Add persistent storage

• Use the command

  mkdir /home/dokku/vv_storage;dokku storage:mount samt-server /home/dokku/vv_storage/samt-server:/app/attachments

  to mount the persistent storage to your application. The corresponding directory on the host machine is /home/dokku/vv_storage.

• Then use the command dokku ps:restart samt-server to restart the application and make this configuration effective.

Adding a Redis Plugin:

• (Not required on Muyan PaaS platform) Add the Redis plugin using the command dokku plugin:install https://github.com/dokku/dokku-redis.git redis.
• Create a new Redis service using the command dokku redis:create samt_redis.
• Link the Redis service to your app using the command dokku redis:link samt_redis samt-server.

Adding LetsEncrypt Plugin:

• (Not required on Muyan PaaS platform) Add the LetsEncrypt plugin using the command dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git.
• (Not required on Muyan PaaS platform) Configure the plugin using the command dokku config:set --no-restart samt-server DOKKU_LETSENCRYPT_EMAIL=<your_email_address>.
• Use dokku domains:add samt-server samt-server.muyan.io to add domain samt-server.muyan.io to your app.
• Add LetsEncrypt HTTPS certificate using the command dokku letsencrypt:enable samt-server.

Setting the Environment Variables:

• Set the GRAILS_ENV environment variable to review using the command dokku config:set samt-server GRAILS_ENV=review.
• Set the PAAS_VENDOR environment variable to dokku using the command dokku config:set samt-server PAAS_VENDOR=dokku.

Binding Domain Name to the Backend App:

• Bind the domain name "samt-server.muyan.io" to your app using the command dokku domains:add samt-server samt-server.muyan.io.

Adding a New Domain Mapping to Frontend and Refreshing LetsEncrypt:

• Add samt.muyan.io to the frontend app using the command dokku domains:add muyan samt.muyan.io.
• Refresh the LetsEncrypt certificate for the frontend app using the command dokku letsencrypt:enable muyan.

Using GitHub Action to Deploy to Dokku:

Place the following file named deploy-to-dokku.yml in your repo's .github/workflows folder.

Ensure the action secret DOKKU_SSH_PRIVATE_KEY is defined for successful deployment.

on:
  push:
    branches:
      - dev

jobs:

  cancel:
    name: 'Cancel Previous Runs'
    runs-on: ubuntu-latest
    timeout-minutes: 3
    steps:
      - uses: styfle/cancel-workflow-[email protected]
        with:
          all_but_latest: true
          access_token: ${{ github.token }}

  deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout Code
      uses: actions/checkout@v3
      with:
        fetch-depth: 0

    - name: Deploy to Dokku
      uses: idoberko2/dokku-deploy-github-action@v1
      with:
        ssh-private-key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}
        dokku-host: 'muyan.io'
        app-name: 'samt-server'
        remote-branch: 'dev'

Configuration Details

Config	Value	Description
Dokku host name	your-host-host	Please change it accordingly
App name	samt-server	The name of the Dokku app
Attachment store folder	/home/dokku/vv_storage/samt-server	This folder is mount to /app/attachments inside container
Postgres service name	samt_postgres	The PostgreSQL service name
Redis service name	samt_redis	The Redis service name
Backend domain name	samt-server.muyan.io	The domain name for accessing the backend service
Frontend domain name	samt.muyan.io	The domain name for accessing the frontend UI (already deployed)

Environment Variables

Variable name	Value	Description
PAAS_VENDOR	dokku	A PaaS vendor flag to be used in docker-entrypoint.sh

TIP

Please ensure the values of the following two DynamicConfigs are correct, otherwise it will cause the attachment upload to fail, or the uploaded attachments will be lost after the container is restarted.

1. The DynamicConfig value for the key attachment.storageEngine (name: Attachment Storage Engine) should be LOCAL_FILE.
2. The DynamicConfig value for the key attachment.local.folder (name: Local Engine Storage Directory) should be /app/attachments.

TIP

The frontend has already been deployed and is accessible. You only need to bind the domain name samt.muyan.io to the frontend app and enable the LetsEncrypt certificate.

Dokku Command Reference

Basic Application Maintenance

• Create an application: dokku apps:create <app-name>

• Delete an application: dokku apps:destroy <app-name>

• List all applications: dokku apps:list

• View application logs: dokku logs <app-name>

• Environment variable management:

  • View all environment variables of an application: dokku config <app-name>
  • Set environment variables for an application: dokku config:set <app-name> KEY1=VALUE1 KEY2=VALUE2
  • Unset environment variables for an application: dokku config:unset <app-name> KEY1 KEY2

• Stop and start applications:

  • Stop an application: dokku ps:stop <app-name>
  • Start an application: dokku ps:start <app-name>
  • Restart an application: dokku ps:restart <app-name>

• Mounting Disks:

  • Create a mount point: dokku storage:mount <app-name> /var/lib/dokku/data/storage:/app/storage Mount /var/lib/dokku/data/storage from the host to /app/storage inside the container.
  • View mount points: dokku storage:list <app-name> View all mount points of an application.
  • Apply mounts: dokku ps:restart <app-name> Restart the application to apply mounts.
  • Remove a mount point: dokku storage:unmount <app-name> /app/storage Remove the /app/storage mount point inside the container.

• Application Domain Management:

  • Set a domain for an application: dokku domains:add <app-name> your-subdomain.yourdomain.com
  • View all domains of an application: dokku domains:report <app-name>
  • Remove a specific domain from an application: dokku domains:remove <app-name> your-subdomain.yourdomain.com

• View Dokku's Help: For any command, you can add the --help parameter to view the command's help and usage.

Redis Plugin

• Create a Redis service: dokku redis:create <service-name>
• Link a Redis service to an application: dokku redis:link <service-name> <app-name>
• Delete a Redis service: dokku redis:destroy <service-name>
• View Redis service information: dokku redis:info <service-name>

PostgreSQL Plugin

• Create a PostgreSQL service: dokku postgres:create <service-name>
• Link a PostgreSQL service to an application: dokku postgres:link <service-name> <app-name>
• Delete a PostgreSQL service: dokku postgres:destroy <service-name>
• View PostgreSQL service information: dokku postgres:info <service-name>

Let's Encrypt Plugin

• Set an email for an application (used for Let's Encrypt certificate expiry notifications): dokku config:set --no-restart <app-name> [email protected]
• Enable Let's Encrypt for an application: dokku letsencrypt:enable <app-name>
• View Let's Encrypt certificate information: dokku letsencrypt:ls
• Renew Let's Encrypt certificates: dokku letsencrypt:auto-renew <app-name>

Feel free to ask if you have any further questions or need additional assistance!

Frequently Asked Questions

What to do if the backend service cannot be accessed?

If the backend service cannot be accessed, check if any port is exposed in the Dockerfile. If so, remove the expose part. Dokku should handle the port mapping automatically. Manually exposing a specific port in the Dockerfile will disrupt Dokku's automatic port forwarding.