Migrate a Micro

💡 This guide is designed specifically for those who have prior experience with Deta Cloud. It provides instructions on how to migrate a Micro into a Deta Space app. If you’re looking to simply learn about Deta Space, it’s recommended to read the new documentation.

Deta Micros are lightweight runtimes connected to an HTTP endpoint with Python and Node.js support.

Deta Space provides the ability to build Space Apps using Micros, offering support for a wide range of languages and frameworks right out of the box.

In this guide, we will walk through the process of migrating your Deta Cloud Micros to a Deta Space App.

⚠️ Deta Cloud support will end on May 1, 2023. If you’re using Micros, we strongly encourage migrating them to Space Apps before then, as Deta Cloud Micros will not be supported after this date.

Requirements and Prerequisites

Before you begin, make sure that you have installed and logged in to the Space CLI on your system. Login instructions for the Space CLI can be found here.

Cloning the Source Code of Your Deta Cloud Micro

The first step in the process of moving your Deta Cloud Micro to a Deta Space App is to pull the source code of a Deta Cloud Micro on to your local system.

You can do it by using the following command in the Deta Cloud CLI:

deta clone --name <micro-name> --project <project-name>

If you are uncertain about the micro-name or project-name, you can retrieve the command from the Deta Cloud dashboard, which is available in Deta Space.

To do this, log in to your Space Canvas, select the Legacy Cloud app, and use the project selector to choose your project. Then, click on the desired Micro in the left sidebar and go to Settings. Finally, copy and paste the command under Clone Micro.

Modifying Your Source Code

After you have your Micro’s code on your local machine, you may need to very slighlty modify it for compatibility with Space.

// on Deta Cloud

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello world!');
});

const port = parseInt(process.env.PORT) || 8080;

module.exports = app;

// on Deta Space

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello world!');
});

const port = parseInt(process.env.PORT) || 8080;
app.listen(port, () => {
  console.log(`helloworld: listening on port ${port}`);
});

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def root():
    return "Hello World"

Initialize a Space Project

After modifying your source code, but before deploying to Space, it is necessary to create a Space project using the Space CLI.

To create a new Space project, execute the following command from the directory of your cloned Micro.

space new

You will then be prompted to provide a name for your project.

? What is your project's name? >

Once you have named your project, the Space CLI will attempt to bootstrap the configuration for your project and prompt you to confirm if you wish to use the configuration. For Python apps, the process will appear as follows:

📦  No Spacefile found, trying to auto-detect configuration ...
👇  Space detected the following configuration:

Micro found in "./"
L engine: python3.9

? Do you want to bootstrap the project with this configuration?

Type y or simply press Enter to use the bootstrapped configuration. This will create a Project on Deta Space and autogenerate a Spacefile for your project. The Spacefile will how to run your app on Space. Additionally, the CLI will create a .space directory locally, which links your local directory to your Space and stores information about the project. It is important to note that this directory should not be included in your version control system and will automatically be added to the .gitignore file.

If the CLI fails to detect the app and generate the configuration, it will generate a blank Spacefile, which you can configure manually. For more information on the Spacefile, please refer to the official documentation here.

When working on Python projects, it is a good practice to include the virtual environment directory in the .spaceignore file because it contains packages and dependencies that are specific to a particular environment and are not required for deployment. For example:

.venv

💡 Space Projects can also be managed through the Builder app on the Space dashboard (also known as Canvas).

Deploying to Space

Once you’ve created a Space project and have a Spacefile locally, you are now ready to deploy your app! Simply run the following command in your terminal:

space push

This command will check the validity of your Spacefile, package the required files, and upload them to the Space build pipeline. The logs will be displayed in real-time on your terminal, allowing you to keep track of the progress and easily identify any potential issues that may arise during the deployment process. Once the deployment is successful, a new revision will be created and an up-to-date Builder Instance of your app will be deployed. You can easily access this Builder Instance through your Space Canvas:

💡 A Builder Instance is a live copy of a Space App that lives in a Space Project. You’re its builder, so it’s yours to control and use as you like, whether for testing or production. You can space push to update its source code, which should take about a minute to reflect on the live instance.

By clicking on the Builder Instance in the Space Canvas, it will open in a new tab with a unique endpoint of the format <alias-random>.deta.app.

Congratulations, you have successfully migrated your app to Deta Space!

There is just one more step to complete the migration.

Authentication in Deta Cloud vs Deta Space

In Deta Cloud, every Micro was publicly accessible by default, and to secure them, users needed to enable authentication and create an API key. On the other hand, Deta Space has a more advanced and comprehensive approach to authentication, where everything is protected with authentication by default, ensuring that only the owner of the app can access it.

Public Routes

In Deta Space, you have the option to make some or all of your Micro’s routes publicly accessible and generate API keys for your private routes.

If you want to make every route of your Micro publicly accessible, similar to the default behavior in Deta Cloud, open the Spacefile created earlier. In the Spacefile, add the public_routes field to the Micro you have migrated and set /* as the public route, as shown below:

v: 0
micros:
  - name: python-app
    src: .
    engine: python3.9
    public_routes:
      - "/*"

The wildcard * after the root endpoint / in public_routes makes every route of the Micro publicly accessible. Space offers much more fine-grained control over which routes you can make public than Deta Cloud.

For more detailed information on this topic, please refer to the post here. Now, let’s move on to finish migrating your Micro.

To apply the changes to your Builder instance, you need to push your app again:

space push

Once the push is successful, you have successfully migrated your Deta Cloud Micro to Deta Space!

If your Deta Cloud Micro wasn’t using API Keys or Custom Domains, you can now update all external references to its <alias-random>.deta.dev url to the new <alias-random>.deta.app url (after testing of course).

If you are using API Keys on Deta Cloud, continue reading.

API Keys

To continue using API Keys with your migrated Micro, you need to enable the api_keys preset in the configuration of your Micro in the Spacefile. This will allow you to secure your private routes with API Keys, just as you did with your Deta Cloud Micro.

Here’s an example of a Spacefile with the api_keys preset:

v: 0
micros:
  - name: python-app
    src: .
    engine: python3.9
    public_routes:
      - "/*"
    presets:
      api_keys: true

Next, run the command space push to apply changes to your Space app. This will enable API keys for your Deta Space Micro, just like they were with your Deta Cloud Micro. To generate an API Key, simply go to your Space Canvas, click on the ellipsis (‘…’) on the tile of your app, and you’ll be able to generate an API Key from there.

Click “Configuration,” and you should be brought to a Configuration menu for your app in Builder. From here, you can click “Create new API Key” to generate an API Key.

With that, you have enabled API Keys for your Micro. You can now access protected routes by passing the API Key as an X-Space-App-Key header in your requests. For more information on API Keys in Space, visit the official documentation here.

Advanced migrations

We have covered the basic migration case, but there are some advanced cases.

Migrating a Micro Tied to Bases and Drives in Deta Cloud

You may have been using Micros with Bases and Drives in Deta Cloud, and want to continue using the data that lives in these Bases and Drives with your migrated Space App.

This is possible in a few steps.

1. Migrate your Micro to Space

First, migrate your Micro to a Space app, by following the guide on the current page, if you haven’t already.

2. Migrate your project to Collections

Second, follow the guide to migrate your Cloud project to Deta Collections. Choose the Project which has the data you want to plug your Space App in to.

3. Generate a Data Key for your migrated Collections

Third, generate a Data Key for your new Collection. You’ll need to save it for the next step.

4. Authenticate against your Collection in your Space App

Finally, we’ll use the Data Key from the previous step to integrate our Space App to the Migrated collection. This is the most involved step but it shouldn’t be too hard.

The principle is to that the Data Key will let us talk to the migrated Collection from the migrated Space App (whether using HTTP or a Deta SDK).

Let’s dive in.

Create an Environment Variable

First, let’s add a [Custom Environment Variable] to our Space App to store the Data Key securely.

Let’s update our Spacefile with an env preset. Here’s an example:

v: 0
micros:
  - name: python-app
    src: .
    engine: python3.9
    presets:
      env:
        - name: MY_DATA_KEY
          description: Integrate my new Space App with my new Collection. Yes!!
          default: "please input your data key"

What we are doing here is creating an environment variable for our Micro, where we can securely store the Data Key for it to access.

💡 If your Spacefile has public_routes or the api_keys preset from previous steps, make sure to leave those in.

Once we’ve updated the Spacefile, let’s deploy our changes to our Builder Instance by using space push.

Update the Environment Variable

Click the ’…’ on your Builder Instance’s tile on the Canvas, then click Configuration.

There should now be a heading that says Environment Variables, with MY_DATA_KEY as the only listed environment variable.

Let’s input the Data Key we stored earlier into the input field and click Save Changes.

Update your Code

Lastly, your code needs to pull this Data Key from the environment and use it to authenticate against your new Collection’s Bases and Drives.

Here’s a few snippets to help you out:

// Micro on Deta Space
const { Deta } = require('deta'); // import Deta

// get the Data Key from the environment
const myDataKey = process.env.MY_DATA_KEY;

// initialize Deta with a Data Key
const deta = Deta(myDataKey);

// connect to existing Bases or Drives
const db = deta.Base('my_existing_base');
const drive = deta.Drive('my_existing_drive');

import os
from deta import Deta

# get the Data Key from the environment
my_data_key = os.getenv("MY_DATA_KEY")

# initialize Deta with a Data Key
deta = Deta(my_data_key)

# connect to existing Bases or Drives
db = deta.Base("my_existing_base")
drive = deta.Drive("my_existing_drive")

If you’re not using the Base or Drive SDKs, you can pass your Data Key as the X-API-Key header using the Base or Drive HTTP API.

Migrating a Custom Domain

Migrating a custom domain from Deta Cloud to Deta Space is possible with a few simple steps without any downtime. To do this, just add your custom domain to your Space app and click “Assign Anyway” if you get a warning about the domain already being in use.

You might be asked to verify ownership of the domain by adding a TXT record to your DNS. Once you’ve done that and the system verifies it, the domain will be removed from your Deta Cloud Micro automatically and traffic will be routed to your Space app without downtime.

If you aren’t afraid of downtime, you can also remove your custom domain in the Deta Cloud Legacy App first and then add it to your Space app.

That’s it! You have successfully migrated your Deta Cloud Micro to Space.

Share with us what you have built, connect with the Deta team, seek answers to your questions, and hang out on our community Discord with fellow Detonians! We would love to have you.

Happy hacking!