OrbitsDocs
esc
    Open Orbits
    Getting startedConcepts

    How Orbits fits together

    Teams, members and roles, projects, deployments, environments, domains and operations, and the IDs that name them.

    A few words come up on every page of these docs. This is what each one means in Orbits.

    Teams

    A team owns everything: its projects, domains, environment variables, Git connections, API tokens and its plan. You can belong to several teams and switch between them; each has its own URL in the web app, orbits.africa/<team>.

    A team's plan is Free or Pro, and billing belongs to the team, not to a person. See plans.

    Members and roles

    Everyone in a team has one role.

    RoleCan
    OwnerEverything, including billing, deleting the team and granting or removing owners and admins. A team always has at least one owner.
    AdminChange project and team settings, connect Git providers, pause, transfer and delete projects, manage API tokens.
    MemberCreate projects, deploy, redeploy, promote and roll back, cancel builds, change environment variables, add domains and DNS records.
    ViewerRead: projects, deployments, logs, domains, and variable keys (never their values).

    Someone who isn't in a team can't see that it exists: its pages answer "not found". Inviting people and changing roles are on teams and roles.

    Projects

    A project is one app: one repository (or one folder, for an upload project), one set of build settings, and one production site. A monorepo with three apps is three projects made from the same repository, each with its own root directory.

    Each project has:

    • a name and a slug, its name in lower case with hyphens. The slug is unique across all of Orbits, because it is the project's free address, <slug>.theorbits.app.
    • a workload: how it runs (a static site, a server app, a worker...). It is set when the project is created and doesn't change. See frameworks.
    • a region, always Abuja (abj-1).

    Project settings are on projects.

    Deployments

    A deployment is one build of one commit, and it never changes once it is built. Pushing again, changing a variable or changing a setting makes a new deployment; it never edits an old one.

    Every deployment is in one of two environments:

    • Production: built from the production branch (or promoted to it). One production deployment is current: it is what your project's addresses serve.
    • Preview: built from any other branch, for checking a change before it reaches production. Each gets its own address.

    Because deployments are immutable, changing what production serves is a matter of moving a pointer:

    • Promote takes a ready preview's commit, builds it with production's variables, and makes the new build current when it's ready.
    • Roll back points production at an earlier production build straight away, with nothing rebuilt.

    A deployment moves through the states queued, building, then ready, failed or canceled. See deployments.

    Environments

    Environment variables are scoped to three environments:

    EnvironmentUsed by
    ProductionProduction deployments.
    PreviewPreview deployments.
    DevelopmentYour own machine: the values orbits env pull writes to .env.local. No deployment runs in it.

    A variable can apply to any mix of them. See environment variables.

    Domains

    Every project answers on its free address, <slug>.theorbits.app. A domain is a name you own, such as shop.example.com, added to the team and pointed at a project's production, at a branch's newest preview, or set to redirect somewhere else. Domains belong to the team, so they appear on the team's Domains and DNS page and on the Domains page of the project they serve. Orbits issues and renews their certificates. See domains.

    Operations

    Most things answer at once. A few take longer, such as deleting a project or a team, or moving a project to another team. Those return an operation: a record with its own ID whose state goes pending, running, then succeeded or failed. The web app waits for it; through the API you poll it until it finishes.

    IDs

    Every object has an ID with a prefix that says what it is. You'll see them in the API, the CLI's --json output and in URLs.

    PrefixObject
    usr_A person
    team_A team
    prj_A project
    dpl_A deployment
    dom_A domain
    rec_A DNS record
    tok_An API token
    op_An operation

    Wherever the API takes a team or a project, it accepts its slug as well as its ID.

    Was this page helpful?

    Updated