How to Migrate your Nanobox Application to App Platform

Warning
The Nanobox service will reach its end of life on March 31, 2021. Please ensure you have migrated all applications off of the service by that date.

Below are some key considerations if you are planning to migrate your Nanobox applications to the DigitalOcean App Platform, however these steps can also be used to migrate your app from other platforms, as they are generally necessary for any migration.

Note
Always be sure to back up data and have a rollback plan before proceeding with any migration.

Nanobox Web, Worker, and Data Components

Your Nanobox app consists of one or more components: Web, Worker, and Data components. These each map directly to App Platform components– Service, Worker, and Database. All of these components will need to be migrated.

Web and Worker Components

Rebuild and Redeploy your Containers

Under the covers, both Nanobox and App Platform work by building your web (service) and worker code into industry-standard containers. Nanobox does this by relying on a Docker installation running on your local development system and App Platform does this for you by running a cloud build against your application source code from a specified Github repository.

The simplest way to rebuild and redeploy your application containers is to create a new app in App Platform and configure it to point to a Github repository containing your application's code. App Platform will attempt to auto-detect your app, and build and run it using commands based on Cloud Native Computing Foundation buildpacks.

If your application needs custom build or run commands, you can specify them during app creation or after an app is created on the Components tab. If you need more flexibility, you can create a custom Dockerfile for your application component and instruct App Platform to build and run your component based on that Dockerfile.

Once you've got your primary web service defined in your App Platform app, you can go to the Components tab of the UI and add more web services and workers as needed.

Ports

By default App Platform expects that all web services will listen on port 8080 (0.0.0.0:8080), just like Nanobox. But this can be overridden by changing the HTTP Port setting for your service.

Environment variables

During app creation or when adding/editing a component you can change the environment variables available to your app components. Ensure all environment variables that your Nanobox-hosted application relies on are defined in your App Platform app.

App Platform also supports many auto-generated and bindable environment variables that can be used to replace Nanobox auto-generated environment variables.

Log Files

Most application's logs are piped to either stdout or stderr. Like Nanobox, App Platform automatically streams stdout/stderr to your app's unified log stream.

Hooks and Cron Jobs

App Platform doesn't support hooks or cron jobs. To replace hooks in App Platform, you can:

Deployment Jobs, akin to Nanobox Deploy Hooks, are coming soon to the App Platform.

To replace cron jobs, you can deploy a Droplet on DigitalOcean with cron configured. Or, alternatively, create an App Platform worker component based off a dockerfile with cron configured.

File Storage

Nanobox Writable Directories

Nanobox writable directories are directories stored in your instances’ local filesystem with writable permissions. Because they are stored locally in each instance, their contents do not persist between deploys or when the instance is decommissioned.

App Platform provides a similar writable container file system without requiring any additional configuration. However, just like Nanobox writable directories, these are temporary and their contents do not persist between deploys. Deploys can happen for many reasons: when you update your application settings, when you change your code with autodeploy enabled, or when DigitalOcean performs periodic maintenance activities.

Network Storage

App Platform does not provide a replacement for Nanobox network storage. Instead, you'll need to re-implement or reconfigure your application to use a different persistent data store such as Spaces or Managed Databases.

Databases

Nanobox allows you to define databases and other data components that run as containerized components of your application. These are good for prototyping and development but may be unreliable for production usage.

App Platform offers two native options for databases:

  • Postgres development databases can be created and managed as part of your App Platform application. Like Nanobox data components, this is most useful for prototyping and development but are not recommended for production usage.
  • Direct connectivity to DigitalOcean Managed Databases running engines such as MySQL, Postgres, or Redis is recommended for production workloads. These can be created in the DigitalOcean control panel and then connected to your application in the App Platform Components tab (or during app/component creation).

If you need to migrate data from a Nanobox data component, please search for that engine's specific documentation for importing databases. Here are the guides for MySQL and Postgres.

External databases

While all Nanobox data components must be decommissioned before Nanobox's end-of-life, you have a choice if you're using external (non-Nanobox) databases:

  • Migrate external databases - to do this, create a matching DigitalOcean managed database and import schema and data from your existing database. See engine-specific documentation for importing databases. Here are the guides for MySQL and Postgres.
  • Leave external databases - you may leave external databases (e.g. Amazon RDS) in place and just configure your App Platform application to access them remotely. Ensure you re-implement or reconfigure your application to access the external database using the appropriate connection details. Note that unlike Nanobox, App Platform only runs applications on DigitialOcean infrastructure. As a result, you may need to modify your external data store to allow connections over the internet. In addition, your application may experience increased latency (degraded performance) as communication now needs to occur between DigitalOcean and external data centers.

Domains

Reconfiguring your domain to point to your App Platform application should be the final step in your migration. Up until this point, any steps you have taken have not impacted your end users yet.

Leave your application up and running on Nanobox while you update DNS records to point your domain to your new application instance on the App Platform.

Before configuring your domain to point to App Platform, you can view and test your application using the default ondigitalocean.app domain provided automatically by DigitalOcean.

At some point before changing your DNS records to point your domain to App Platform, you must configure your App Platform app with your custom domain in the Settings tab of your app or via the app spec. This change will not cause any traffic to your domain to begin flowing to App Platform – it is a necessary pre-step before updating your DNS records.

Once you're comfortable that everything is running as expected on App Platform, update your domain's DNS records with a CNAME that points to your App Platform default domain. Remove any DNS records that reference your Nanobox application. Before making any changes, save your existing DNS records as part of your rollback plan.

Depending on your DNS settings and provider, updates can take days to fully propagate. You can reduce the time to live (TTL) on your DNS records to reduce the propagation time of your new DNS configuration.

CDN

All App Platform apps automatically have the Cloudflare CDN placed in front of them to improve your web site performance around the world. If you have an CDN in front of your Nanobox app, you should disable it before reconfiguring your domain to point to your App Platform application.

SSL/TLS (HTTPS)

All App Platform apps automatically have TLS certificates generated and managed for them. This means all domains that have been configured for an app will be https:// accessible.

App Platform does not support bringing your own certificates.

Engines

Nanobox uses Nanobox-specific engines to define, prepare, and build runtime environments for web and worker components. App Platform supports two mechanisms for achieving these same outcomes: