You’re starting an exciting journey building web applications for a new personal computer on the internet: Deta Space. This guide is meant to help you build personal cloud apps with Deta Space, from A to Z.
💡P.S. Make sure the Developer Mode toggle is enabled when you signup.
After you log in, you should see a screen like this.
This is your Horizon, which is a home for all your apps: what you create and 3rd party apps you install. The command bar at the bottom is called Teletype, which provides you with many context-specific actions to help you navigate Space (like Searching the Docs). If you ever aren’t sure what to do, you can open Teletype and see what’s there. The blue app is called Builder and is your companion for building apps on Deta Space, along with the Space CLI.
To build apps, you need the Space CLI on your local machine. Download it with one of the following commands:
To install the Space CLI on Linux, open a Terminal and enter:
To install the Space CLI on Windows, open PowerShell and enter:
To install the Space CLI on MacOS, open a Terminal session and enter:
After it downloads, you need to use the command
space login to authenticate with the CLI. This requires an Access Token, which you can get by clicking the Settings action from Teletype on your Horizon.
❗️ If you encounter
command not found: spaceafter a successful installation, please try to restart your terminal session.
A Space app is different from a normal web app. A normal web app on the “public cloud” is one centralized app that serves many users.
On Space, each user gets their own personal copy of an app, in their own personal cloud. Space apps and their data are private by default, meaning they belong to users, who have to be logged in to use them.
As a developer, you build assuming that you’re the only (already authenticated) user. You can use your favorite programming languages and frameworks, but you don’t have to think about authentication code or data separation. Of course you can still build public facing features or applications that don’t have auth, like websites.
With Deta Space, you can build all sorts of web applications for yourself and keep it that way. But the personal cloud also has a powerful publishing model — you’re one step away from making your app available to almost anyone in the world with an internet connection.
To create a new project, open a new terminal, navigate into a new directory (or the directory of an existing app you want to push to Space) and run the
space new command:
Enter a name for your Project. The Space CLI should try to detect applications in your local directory. If found, you can see the config bootstrapped by the CLI for those applications in a newly created file called the
Spacefile. If you used the Builder UI or have an existing Builder Project, you can use the CLI command
space link to link a local directory with your Builder Project.
Your Project should now appear when you open the Builder app, where you can test, run, manage and publish your apps with Space.
Deta Space has its own runtime — the Space Runtime — that can run almost any type of web app. It supports most programming languages and frameworks.
Spacefile contains the configuration of your app and is used by Deta Space to understand what your app looks like and how to run it.
Here’s an example
Spacefile for a To Do app built with a static frontend and a Node.js backend:
Check out the Spacefile reference for all available options.
A Space app runs on serverless compute units called Micros. A Space app can contain up to five Micros, which run most programming languages and frameworks.
Here’s what the required fields in the
name: identifies your Micro inside your app
src: the location of your the Micro’s code in your local directory (relative to the root)
engine: the programming language or framework for your Micro
There are many optional fields that you can use, depending on what your app does. With the
Spacefile you can make Micros do many things, among them:
- provide Space’s build pipeline with build commands for your Micro via
- provide the Space CLI with a command to spin up your Micro locally via
- indicate on what relative path to serve any given Micro via
- make individual routes public via
- create scheduled tasks via
Check out the Spacefile reference for all available options.
If you’re building something like a website and need parts of your app (or the whole thing) to be public facing, check out how to use the
public_routes fields in the
Deta Space offers persistent data storage for Space apps with Collections. Every Space app gets its own Collection. End users of an app are the ones with access to this Collection — data is meant to belong to them.
Collections offer two persistent storage services:
To get started writing data or files to Base or Drive, you can use the Deta SDKs or Deta HTTP APIs. Authentication is fully managed by Space if you use the SDKs and the
space dev command for local development.
Base SDK Code Snippet
You can also manually authenticate against any Collection using a Data Key, which you can get from your Builder Project, under the Develop / Data tab.
There is also a Data Key in the environment of every Space app, stored as
Base HTTP API Code Snippet (with Manual Auth)
The Space CLI offers support to run your app locally, emulating how your app runs in Space with the command
space dev. This command starts up your Micros, imitates Space’s routing locally, and authenticates your local development environment with your Project’s Bases and Drives.
space dev, you will need to provide a
dev parameter to every Micro in your
dev parameter is the command
space dev uses to start a Micro’s development server. Make sure the command starts your web server on the port specified with the
PORT environment variable, with port
XXXX as a fallback.
Once you have your app working locally, you can push it to the internet on Deta Space with a single command, from your Project’s local directory:
This command will package all your code files and pass them to the Space Build Pipeline, streaming build logs back to your machine. If your build completes successfully, a revision (an installable and runnable package of your app) will be created and installed to your Project’s Builder Instance.
Builder Instances are fully functional apps running in Space, tied to a Project. You can use them to test and debug your app on Space before releasing it to the world. Or you can use them as a flexible personal copy of an app you built for your own use. They offer all the features that normal Space apps offer, and are always based on a specific Revision of a Project.
When you push a Project’s code for the first time, a Builder Instance is automatically added to your Horizon (signified by the purple
DEV marker). You can also view them in your Builder Projects. Data stored is shared across your entire Builder Project — both your Builder Instance and your local setup with
space dev have access to the same data.
As a real copy of your app running in Space, the Builder Instance is perfect for end to end tests in a real production environment. If something goes wrong at runtime, you can inspect the logs to see what the issue may be. Logs are viewable from your Project in Builder, or from your app’s context menu on the Horizon, just like on any other app.
Read more about debugging with Space.
You can use your Builder Instance as you would any other app. Click on your Builder Instance, to open it in a new tab. If your app is an API, use the URL outside the browser.
You also have all the normal features of a Space App:
- Here’s how you set environment variables
- Here’s how you view your data
- Here’s how you set a Custom Domain
Once you’ve built something that runs in your Builder Instance, you’re one step away from publishing it to just about anyone in the world.
You can use the CLI or Builder UI to create a Release, which will be installable in others’ personal clouds via a link:
Using the CLI, use the following command to release your app:
If you use the additional CLI flag
--listed, your app will be publicly discoverable and installable via Deta Discovery.