Core concepts
The plain-language vocabulary the rest of the docs use — organizations, projects, deployments, services, servers, domains, environments, and runtimes.
Openship has a handful of words it uses over and over. Once you know them, the rest of the docs read easily. Here's a way to hold them together: your code is a recipe, Openship is the kitchen, and the pages below are the parts of the kitchen. This page is the short glossary — one idea each, in plain words.
Organization (workspace)
Like a shared filing cabinet for you and your team.
Everything you make in Openship lives inside an organization (the dashboard also calls it a workspace). Your projects, servers, and domains all belong to the organization — not to you personally. That's what lets a team share them.
You can belong to more than one organization, and each person in one has a role: owner, admin, or member. The role decides what they're allowed to do. See Permissions.
Project
Like one dish on the menu — one app you want online.
A project is a single app you deploy. It remembers where your code comes from (a GitHub repo or a folder on disk), how to build it, and everything attached to it: its deployments, web addresses, environment variables, logs, and settings.
You don't have to configure most of that by hand — Openship looks at your code and fills in sensible defaults. Making one is covered in the Quickstart.
Environment
Like having a real kitchen for customers and a test kitchen for trying recipes.
An environment is a separate copy of your project. The two you'll meet most are:
- Production — the live version real people use.
- Preview — a throwaway copy for trying changes before they go live.
(There's also a development environment for local work.) Each environment keeps its own deployments, its own environment variables, and its own web address, so testing something never touches what's live.
Deployment
Like one printing of a book — every deploy makes a new edition.
A deployment is one attempt to build your code and put it online. Every time you deploy — or, with auto-deploy on, every time you push to GitHub — Openship makes a new one. Each successful release gets a version number (v1, v2, v3…) so you can tell them apart.
Only one deployment is live at a time. The others are kept as history, so if a new one breaks you can roll back to an earlier one. Each deployment records which commit it built, whether it succeeded, and the URL it went live at.
Service
Like a restaurant with a kitchen, a bar, and a dishwasher — separate stations working together.
Most projects are one thing. But some apps are really several pieces running side by side — a website, a database, a cache. Each piece is a service. Openship supports two shapes:
- Compose — services defined in a
docker-composefile (for exampleweb,db, andredis). - Monorepo — several apps living in one repository, each built as its own service.
Services can depend on each other, each can have its own public address or stay private, and a single deploy brings the whole set up together. See Multi-service & Compose.
Domain
Like the street address on your house.
A domain is the web address people type to reach your app, such as app.example.com. Openship can give a
project a free address to start with, and you can also connect a custom domain you own.
When you add a custom domain, Openship checks a DNS record to confirm it's really yours, then turns on HTTPS for you automatically. One domain per project is marked primary (the main address). Full details are in the Domains API.
Server
Like renting a counter in someone else's kitchen — you bring the recipes, they provide the space.
A server is your own remote computer that Openship connects to over SSH to run your apps. You add it once with its connection details (host, user, and a key or password); after that Openship can deploy to it. One organization can have several servers.
You only need a server for the 'server' runtime
If you deploy locally or to Openship Cloud, you don't add a server at all. Servers are only for running your apps on machines you own.
Runtimes
Like choosing whether to cook at home, at a friend's place, or order from a restaurant.
When you deploy, you pick where the app actually runs. On the deploy screen this choice is called the deploy target, and there are three:
- Local — on the same computer that's running Openship. Great for trying things out on the desktop app.
- Your server — on one of your own servers, reached over SSH and, by default, run inside Docker.
- Openship Cloud — Openship runs it for you, no machine of your own required.
You choose it on the deploy screen, and you can move a project between them later. How each one works under the hood is explained in the Runtime model.