Projects and environments: grouping related services
Group the services that make up one application into a project, split them across environments like Production and Staging, then rename or remove one safely.
What this covers
An application is usually several services, and it usually exists more than once: a production copy and a staging copy. Projects and environments are how Voroa models that. A project groups the services that belong to one application, and each environment holds its own copy of those services with its own variables and its own databases, so a mistake in a test environment cannot reach real users.
Creating a project
Go to Projects and choose New project. You give the project a name, and you name its first environment at the same time. That field arrives filled in with Production, because that is what most projects want; change it if your first environment is something else, such as Staging.
Every project has at least one environment, and the first one you create is its default.
Alongside the name you type, Voroa derives a short identifier from it. “My QA” becomes my-qa. You
never have to type the identifier yourself, and two environments in the same project cannot end up
sharing one, so a second environment called “my qa” is refused rather than silently merged.
Adding services to a project
When you create a service, the form asks which project and environment it belongs to. Databases work the same way. Choosing them at create time is how a service ends up grouped, and it costs nothing to change your mind later by creating the service where you want it.
Adding more environments
Open the project and choose New environment. Give it a name; the identifier is derived the same way. How many projects and environments you can create depends on your plan. When you reach the limit, Voroa tells you the number rather than failing quietly.
Renaming an environment
You can rename an environment at any time from the project page. The rename changes the name you see; the derived identifier stays as it was, because the services already inside the environment are grouped by that identifier and changing it would separate them from their own environment.
If you want a different identifier, create a new environment and place new services in it.
Deleting an environment
Two rules protect you here.
The default environment of a project cannot be deleted. A project with no environments has nowhere to put a service, so the first one stays.
An environment that still contains services cannot be deleted either. Voroa tells you how many are still in it and asks you to move or delete them first. This includes any preview environments generated from pull requests, which is deliberate: deleting the environment underneath a running preview would leave that preview pointing at something that no longer exists.
Renaming or deleting a project
Open the project and choose Settings. You can rename the project at any time; the new name shows everywhere in your dashboard.
Deleting a project follows the same two rules as deleting an environment. Your default project cannot be deleted. A project that still contains services, including any pull request previews, cannot be deleted either: delete those services first. Deleting a project removes it and its environments, and cannot be undone. Any environment group that was limited to this project or one of its environments is kept and becomes available to the whole workspace, so review its scope afterwards.
Protecting an environment
An environment can be marked protected. After that, anything inside it that takes something away needs a workspace administrator. A developer attempting it gets a clear refusal rather than a silent failure.
What counts as taking something away:
- deleting a service or a database
- stopping one
- removing a custom domain, which takes a running service off its address
- deleting a scheduled task
- rotating a database password, which stops every application already using the old one
- importing over a database
Deploying is not blocked. That is what the environment is for.
Only an administrator can protect or unprotect an environment. A developer who could turn the protection off has not been stopped by it, only delayed.
Changing settings is not blocked - environment variables, secret files and the rest stay editable. Protection is about not losing a service, not about freezing one.
Three things it deliberately does not do:
- It does not restrict reading anything. Voroa never shows a stored secret back to anyone - variables and secret files are write-only, and a database’s connection details come back with the password masked - so there is nothing to protect on the read side that is not already protected everywhere.
- It never blocks removing a database user. If a credential leaks, revoking it is the thing you need to do immediately, and a protection setting is not allowed to stand in the way.
- It never blocks cancelling an import. Stopping something you started is a safe action, and a stop button that needs somebody else is worse than no protection at all.
Turning protection off again on an environment leaves everything else as it was; the services inside are untouched either way.
What is not available yet
- Blocking private network traffic between two environments in the same project.
- Moving an existing service from one environment to another. Create it in the environment you want.
- Declaring your projects and environments in a file in your repository.