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.
If your micro is running on a Node.js runtime, modifications to the code will be necessary.
In Deta Cloud, Micros running on Node.js runtime require the app instance of the framework, located in index.js
to be exported. For example:
// 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;
In Deta Space, instead of exporting the app instance, you need to make sure that your Micro listens on the port specified in the PORT
environment variable.
The following is an example of how the code mentioned earlier would be modified:
// 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}`);
});
Once the modification is complete, you are now ready to deploy to Space.
If your Deta Cloud Micro is running on a Python runtime, no changes to your code are necessary.
Hereâs an example of a âHello Worldâ server running in Python with FastAPI:
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 theapi_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!