Monorepo support: deploy many services from one repo
Run several Voroa services from one repository. Give each its own root directory, and use build filters so a push rebuilds only the services it changed.
What a monorepo is
A monorepo keeps more than one application in a single repository. For example, a front end, an API and a background worker can each sit in their own folder:
my-repo/
web/ front end
api/ API server
worker/ background jobs
On Voroa each of those is a separate service. All three connect to the same repository, and each one is told which folder to treat as its own. Two settings make that work:
- Root directory: the folder the service builds and runs from.
- Build filters: which file changes start a new deploy of that service.
Setting a root directory
The root directory is the folder, relative to the top of your repository, that Voroa treats as the
service’s project root. Your build command and start command run from inside that folder, and Voroa
looks for your project files (for example package.json or requirements.txt) there.
You can set it when you create the service, or change it later:
- Open the service and go to Settings, then Build & Deploy.
- Next to Root directory, choose Edit.
- Pick the folder from the list, or type its path, for example
apiorapps/api. Leave it as/to use the top of the repository. For a GitHub repository the list shows every folder, and marks the ones that hold app files. - Save, then deploy. The new root directory takes effect on the next deploy.
For the example above, you would create three services from my-repo, with root directories web,
api and worker.
When you need one even without a monorepo
Some repositories hold a single app, but inside a folder rather than at the top. If the top of your repository holds only one folder and no project files, the build has nothing to build there and fails. Set the root directory to that folder.
my-repo/
restaurant-api/
package.json
src/
Here the root directory should be restaurant-api, not /. When you create a service from a
repository shaped like this, Voroa notices the app files are one folder down and picks that folder
for you.
Building only what changed: build filters
By default, every push to a service’s branch starts a new deploy of that service, wherever the change
is. In a monorepo that means a change to web/ also rebuilds api and worker, and you spend build
time on services that did not change.
Setting a root directory does not limit auto-deploys on its own. Use build filters for that.
Build filters live under Settings, then Build & Deploy, and have two lists:
- Included paths: if you set any, a push deploys this service only when at least one changed file matches one of them. Leave it empty to count every file.
- Ignored paths: changed files that match these never start a deploy.
A push deploys the service when at least one changed file is included and not ignored. Write one pattern per line. Patterns are relative to the top of the repository, not to the root directory.
| Pattern | Matches |
|---|---|
api/** |
every file under api/, at any depth |
api or api/ |
the same: a folder name matches everything inside it |
*.md |
Markdown files at the top of the repository only (* does not cross a /) |
**/*.md |
Markdown files in any folder |
package.json |
that one file at the top of the repository |
For the example repository, the api service would use:
Included paths:
api/**
packages/shared/**
Ignored paths:
api/**/*.md
So a push that changes only web/ or a README leaves api alone, and a change to the shared package
rebuilds it.
Good to know
- Build filters apply to automatic deploys from a git push (GitHub and GitLab). A deploy you start yourself from the dashboard always runs.
- If Voroa cannot tell which files a push changed, it deploys rather than risk skipping a real change.
- A skipped push does not appear in the service’s deploy history.