Getting started

Core concepts

The terms used across Elula and these docs.

This page explains the main ideas in Elula: workspaces, apps, environments, deployments, access and your Google Cloud project.

Workspace

A workspace (called an "organization" or "org" in the CLI) is where your team's apps live. Each workspace has its own members, apps, Google Cloud connection, team domain and subscription.

You can belong to more than one workspace. The CLI works in one active workspace at a time:

elula whoami          # who you are, your active workspace and your role
elula org list        # all your workspaces (the active one is marked)
elula org switch acme # make another workspace active (slug, name or ID)

elula projects and elula init use the active workspace.

Roles

Every member of a workspace has one role:

Role	What they can do
owner	Everything, including workspace settings: Google Cloud, access policy, domains and audit log
admin	Create apps, manage all apps, manage members, review approvals, view billing
member	Create apps and manage their own apps
billing	View and manage the subscription; can't see or deploy apps

Workspace settings are owner-only. See Team and roles.

You can also add people to a single app as collaborators, with the role viewer or editor:

elula collaborators add sam@example.com --role editor

App

An app (called a "project" in the CLI) is one deployable thing built from a Git repo, a branch and, optionally, a subdirectory of the repo. An app is one of two types.

	Service	Job
Use it for	Web apps and APIs that answer HTTP requests	Code that runs and exits: batch work, reports, ETL
Gets a URL	Yes	No
Runs when	Requests come in	You run `elula job run`, or a cron schedule fires
Scaling	Automatic, between a min and max number of instances	Each run goes to completion

Pick the type when you create the app:

elula init                 # service (the default)
elula init --type job      # job

A folder is linked to an app by a .elula.json file that elula init or elula link writes. CLI commands run from that folder (or any folder below it) act on that app.

See Deploy a web app or API and Jobs and schedules.

Environment

Each app has an environment label: dev, staging or prod. It defaults to dev. Set it when you create the app:

elula init --env prod

The label shows in elula projects and elula status. All apps in a workspace deploy to the workspace's connected Google Cloud project, whatever their label.

Region

Apps run in one Google Cloud region: asia-southeast1 (the default) or us-central1. Choose it at creation with elula init --region, or move an app later with elula project set-region. Moving a service changes its URL.

Deployment

A deployment is one build and release of an app at a specific Git commit. Each deployment moves through these statuses: pending, building, deploying, then success, failed or cancelled.

A deployment starts when:

you run elula deploy,
you click Deploy in the dashboard,
someone pushes to the app's branch and auto-deploy is on.

Elula keeps the history, so you can roll back to an earlier successful deployment without rebuilding:

elula deployments     # recent deployments
elula rollback        # back to the previous successful one

You can also deploy a preview of an open pull request with elula preview. See Pull request previews and Deployments and rollbacks.

Access: private and public

Each service is either:

Private: only people signed in with a Google account on your workspace's verified team domain can open it.
Public: anyone with the link can open it.

New apps use the workspace default unless you choose. Making an app public can need approval from an owner or admin, depending on the workspace policy. See Private and public apps.

Team domain

The team domain is the Google Workspace domain your team signs in with, for example example.com. A workspace owner verifies it by adding a DNS TXT record.

Private apps are only available after the team domain is verified. Until then, new apps are public.

Your Google Cloud

Elula deploys into a Google Cloud project that your workspace owns. An owner connects it once in workspace settings. After that:

builds run on Cloud Build in your project,
apps and jobs run on Cloud Run in your project,
managed Postgres databases run on Cloud SQL in your project.

Google bills you for that usage directly. See Connect Google Cloud.

Subscription

A workspace needs an active subscription to create apps and deploy. Apps that are already running keep running without one. See Billing.