Deploying from the IDE¶
velonde deploy, run in a project directory, builds the project inside the workspace and publishes it.
This page covers what the workspace recognises, what it uploads and builds, how to read the output
when a build fails, and how several people work on one app.
You need neither Docker on your machine nor any cluster configuration. The workspace reads the
files, works out what kind of project they are, builds an image with the packages the project
records, pushes it to the workspace's registry and registers the result. Run the command in a
terminal of an IDE session on the workspace, because the session is how the workspace knows who is
deploying. Outside a session the command reports that it cannot reach the deploy service. In
R, velonde::deploy() and the other functions of the velonde package do the same from the console.
In VS Code, the Deploy button in the status bar runs the same deploy, and in RStudio the addin
"Deploy to the workspace" does (see The IDEs).
What deploys, and how it is recognised¶
| In the directory | Kind | Runs as |
|---|---|---|
app.R, or ui.R and server.R |
shiny |
an app on the apps page |
_targets.R |
targets |
a pipeline that runs as jobs, now or on a schedule, with nothing on the apps page |
_server.yml with engine: mcptools |
mcp |
an MCP server at /api/<name>/, registered in your colleagues' coding agents |
plumber.R |
plumber |
an API at https://apps.velonde.<your domain>/api/<name>/ |
app.py, main.py, streamlit_app.py or server.py importing fastmcp |
mcp-python |
an MCP server of Python tools, as above |
the same files importing fastapi or vetiver, with the application object named app or api |
fastapi |
an API at /api/<name>/ |
the same files importing shiny |
shiny-python |
an app on the apps page |
the same files importing streamlit |
streamlit |
an app on the apps page |
the same files importing dash |
dash |
an app on the apps page |
*.qmd with server: shiny, *.Rmd with runtime: shiny |
Shiny document | an app on the apps page |
*.qmd, _quarto.yml or *.Rmd without Shiny |
static document | rendered at build time and served as files on the apps page |
*.ipynb |
notebook |
a Jupyter notebook, rendered at build time and served as files on the apps page |
type: script or type: script-python in velonde.yaml, with an R or a Python file as entry |
script, script-python |
a pipeline that runs the file as jobs, with nothing on the apps page |
a static document with schedule: or after: in velonde.yaml |
scheduled report | rendered in runs, each render a new version on the apps page |
The workspace checks the files in the order of the table, and Quarto files before R Markdown files
and notebooks. A Quarto document is a quarto-python document, rendered with the Jupyter
engine, when a pyproject.toml, uv.lock or requirements.txt is next to it, or when it has
Python chunks and no R chunks. A Shiny document in Python becomes a Shiny for Python app. Every
kind is one language: the Python twin of an R kind ends in -python.
To override detection, set type: and entry: in velonde.yaml. A directory with
several documents needs entry:, unless one of them is index.qmd or index.Rmd, or the
directory has a _quarto.yml, which the workspace renders as a Quarto project.
A directory with its own Dockerfile is built from that file, if your workspace allows it.
Build from your own Dockerfile explains how.
Kinds describes what each kind does once it runs and how you reach it.
Dependencies¶
R packages come from renv.lock. Run renv::snapshot() before you deploy, and the build
restores exactly those packages on top of the workspace's package stack. Python packages come from
uv.lock, which uv lock writes. A requirements.txt also works, but it pins nothing.
The workspace looks up the system libraries that the R packages in the lock file need and installs
them. velonde sysreqs shows that list in advance. If the lookup misses a library, add it under
system-packages in velonde.yaml.
A workspace in stack mode (deploy_mode in its configuration)
restores no packages. An app may use the packages of the workspace's stack and no others, and builds
take seconds. The deploy output says which mode the workspace is in.
Install R packages inside the project, with renv::install() or install.packages() while the
project is active. A package you install in a plain session outside a project goes into your
personal library, which renv does not record.
What is uploaded¶
The workspace uploads everything in the directory except .git, .Rproj.user, .Rhistory, .RData,
.Ruserdata, renv's library and staging directories, .claude, .posit, .quarto, .venv,
_targets, _store and the usual caches. These names are left out at any depth, and the
deploy says so for a _targets or _store directory below the top of the project.
.gitignore does not apply. The upload is compressed and limited to 200 MB, so keep large
data files outside the project, or leave them out with .velondeignore. velonde deploy checks the
size before it uploads anything.
A file named .velondeignore at the top of the project lists what else the upload leaves out. It
takes the patterns of a .gitignore: a name matches at any depth, a pattern with a slash
counts from the top of the project, a trailing slash means directories only, and a line that
starts with ! takes a path back.
The deploy lists what the file left out. velonde.yaml is always uploaded. An app bound to a
repository is built from the repository, not from an upload, so .velondeignore has no effect
there: mark such paths with export-ignore in a .gitattributes file in the app's directory.
A symbolic link to a file or directory inside the project is uploaded as what it points to,
so a data link to raw/data reaches the app as a directory. A link to a path outside the
project is left out, and the deploy names it in a warning: the build cannot see that path.
With require-clean: true in velonde.yaml, the workspace uploads the files of the last commit and
the .Renviron or .env, and nothing else in the directory.
The workspace takes .Renviron (R) or .env (Python) out of the upload and stores it as the app's
secret, so the file never enters the image. See
Secrets and environment.
The first deploy¶
$ velonde deploy
velonde: packing /home/rstudio/sales as 'sales'
velonde: building sales as registry.velonde.acme.example/apps/sales:latest (shiny; mode: renv, Dockerfile: generated, renv.lock: yes)
velonde: system packages: libcurl4-openssl-dev libssl-dev
...
velonde: pushed registry.velonde.acme.example/apps/sales:latest (sha256:3f9c1a7e2b04)
velonde: app registered; the apps server restarts (about a minute)
velonde: https://apps.velonde.acme.example/app/sales
velonde: wrote velonde.yaml (app name 'sales'); edit it to change title, groups, env, sizing
The app takes the directory's name in lower case, unless --name or velonde.yaml sets another.
A new app restarts the apps server, so its URL may take about a
minute to open.
The first deploy writes a velonde.yaml that sets name and title and lists the
other keys of the project's kind, commented out, with their defaults. Edit it next: set the
title that the apps page shows and, if not everyone on the workspace should see the app, the groups
that may.
In a git repository, the deploy records the commit it was built from. It warns when the
directory has changed or untracked files, or files that git ignores, because the upload takes
those as well and what runs then differs from the commit.
With require-clean: true in velonde.yaml, the deploy refuses while a committed file has
changes or velonde.yaml itself is not committed, and uploads the commit's files only, so
untracked and ignored files neither block the deploy nor reach the app. A directory outside
git deploys as well.
Redeploys¶
If you run velonde deploy again and neither the directory nor the workspace's base image has changed,
the workspace skips the build. The output says nothing changed since the last deploy, and the workspace
still stores .Renviron or .env as the app's secret. Use --force to build anyway.
If anything in the directory has changed, velonde.yaml included, the build runs. It reuses the
cached layers of the packages unless the lock file or the system packages changed. The workspace
pushes the image under the same name and adds an entry to velonde history. New sessions of the
app start the new image, and open sessions keep the old one.
For an app or document, a change to title, description, access-groups, env,
resources, prestart, seats-per-container or uses in velonde.yaml restarts the
apps server (about a minute). An API or MCP server restarts with every new build,
without failed requests. The velonde.yaml reference lists
what a change to each key costs.
Reading the output¶
Every line starts with velonde:. These are the lines to look for:
warning: N changed or untracked file(s) …: the deploy goes ahead, andvelonde historymarks it with*. Commit first if the deploy should match a commit.warning: N git-ignored file(s) or folder(s) … are uploaded as well: the same for files that git ignores, such as rendered output. Delete them, or setrequire-clean: true.nothing changed since the last deploy …; not rebuilding: see Redeploys.waiting for a build slot: other builds are running (the workspace'smax_builds). The deploy continues by itself. When several people wait, the one with fewer builds running goes first.system packages: …: the apt packages the build installs for the lock file andsystem-packages.N variable(s) from .Renviron stored as the app's secret, followed bykept the values set with 'velonde env set' for: …for the keys thatvelonde env setoverrides.pushed … (sha256:…): the build succeeded.velonde historylists this digest.app registered,new sessions of the app use this build,app settings changed,pre-started app: the apps server restarts …: what happened to a running app.API service rolling out,MCP server rolling out,pipeline registered: the kinds that are not apps. The line says how to reach the result.moves from internal to public(or another pair):audiencechanged, and the app moved to the other server.public: anyone can open it without loginfollows for a public app, with the number of viewers per container and the limit.connection to the deploy service lost: the deploy service restarted or the network dropped. The build continues and the workspace records it when it ends.velonde history NAMEshows it a minute later. The command exits with status 0, because the deploy has not failed.- The last line is the URL. If the output ends in
velonde: FAILED, the lines above it are the build log. Read it from the bottom up.
A problem with what you uploaded stops the deploy before any build starts. It shows as a
single line with an HTTP status, such as velonde: 400: velonde.yaml: …, without velonde: FAILED.
Checks before a deploy¶
Every deploy runs four checks. Your workspace admin decides for each one whether a finding stops the
deploy, is only listed, or is not looked for (check_* in the workspace's
configuration). The table shows the
default. The checks run on the workspace, so the same rules apply to everyone who deploys, to the
coding agents and to apps that deploy from a repository.
| Check | Default | What it looks for |
|---|---|---|
| Secrets | stops the deploy | Passwords, API keys, tokens and private keys in any file of the project, including a password in a connection URL such as postgresql://user:password@host/db. The check uses the rules of gitleaks and two of the workspace's own. |
| Vulnerabilities | stops the deploy | Packages in renv.lock, uv.lock or the pinned lines of requirements.txt with a published vulnerability. The deploy stops when the vulnerability is rated high or critical, or has no rating, and a fixed version exists. Every other vulnerability is listed. The workspace keeps its own copy of the OSV database, so your package list does not leave the workspace. |
| Code | listed | Patterns that are a common way in for an attacker: running a shell command, building SQL by pasting text together, putting user input into HTML unescaped (HTML(input$…), unsafe_allow_html=True, tables with escape = FALSE), running code made from text (eval(parse(text = …)), eval()), loading pickles or YAML unsafely, and turning off the check of TLS certificates. Python code is checked with bandit. |
| Tests | stops the deploy | Every R and Python file parses, and the project's tests pass: tests/testthat with testthat for R, tests/ with pytest for Python. This check runs in the build, after the packages are installed. |
An app with its own Dockerfile and an R or Python package get the first three checks. The workspace
does not run tests in a Dockerfile it did not write, and a package runs its own with check:
true in velonde.yaml (R and Python packages).
To see the result before you deploy, run velonde check in the project's directory
(velonde::deploy_check() in R). It runs all four checks, the tests in your session, and changes
nothing on the workspace.
The first three run before the build. When one of them stops the deploy, the output is a
single message that starts with velonde: 422: the checks before the deploy found …. It lists
each finding with its file and line, and nothing is built. Findings that do not stop the
deploy appear as lines starting with warning: before the build log.
Fix a finding¶
- A secret. Move it into
.Renvironor.envnext to the sources. The workspace stores those files as the app's secret and passes their values to the app as environment variables (see Environment and secrets).velonde env setdoes the same without a deploy. Then replace the secret where it was issued, because it has been in your code and possibly in your git history. - A vulnerability. Update the package:
renv::update("pkg")andrenv::snapshot()in R,uv lock --upgrade-package pkgin Python. The message names the version that fixes it. - Code. Change the code, for example to
glue::glue_sql()or theparamsargument ofDBI::dbGetQuery()for SQL. - A test. Run the tests in your session (
testthat::test_dir("tests/testthat"),uv run pytest), fix them and deploy again.
Mark a finding as accepted¶
If a finding is not a problem for your app, mark it in the project. The mark is part of your code and visible to anyone who reviews it.
| Check | How |
|---|---|
| Secrets | # gitleaks:allow at the end of the line, or the finding's fingerprint in a .gitleaksignore file. |
| Vulnerabilities | An entry in osv-scanner.toml next to the lock file, with a reason and an end date: [[IgnoredVulns]], id = "GHSA-…", ignoreUntil = 2026-12-31, reason = "…". |
| Code | # nosec on the line. |
What the build has for tests¶
The tests run without the app's secrets, environment variables and network shares, because the
build has none of them. A test that needs them can skip itself in the build: testthat::skip_on_ci()
in R, or a check of the CI environment variable in Python, which the build sets. Tests that
drive a browser (shinytest2, Playwright, Selenium) are left out, because the build has no
browser.
When a build fails¶
Fix the first real error in the log. Lines starting with #N are build steps.
| Message | Cause | Fix |
|---|---|---|
cannot open shared object file in the load check |
A package needs a system library at run time. | Run velonde sysreqs and add the apt package under system-packages. |
there is no package called 'X' in the load check |
X is not in renv.lock. |
Run renv::install("X") and renv::snapshot(), then deploy again. |
this workspace builds apps from a fixed package stack after a package that does not load |
In stack mode, the app uses a package outside the workspace's stack. | Remove the package, or ask your workspace admin to extend the stack. |
renv::restore() fails to install a package |
A compile error, usually from a missing -dev library. |
Run velonde sysreqs, then add the package under system-packages. |
ModuleNotFoundError in python -c 'import …', or imports what is not installed |
A dependency is missing from uv.lock. |
Run uv add … and deploy again. |
AttributeError: module 'app' has no attribute 'app' |
The FastAPI application object has another name. | Name it app or api. |
quarto render writes the Shiny document's app to this file |
A Shiny document in Python sits next to an app.py of yours. |
Rename your file, or move the document to a directory of its own. |
a Dash app cannot run in warm or shared containers |
velonde.yaml of a Dash app sets prestart or seats-per-container. |
Remove both keys. |
type script needs entry: <file>.R (or .py for script-python) |
A script needs its file named, unless the directory has a pipeline.R (or pipeline.py). |
Set entry: in velonde.yaml. |
after: there is no pipeline …, after: pipeline … belongs to … |
A pipeline under after: does not exist, or does not admit the owner. |
Deploy it first, or ask its owner to add one of your groups to its access-groups. |
email: this workspace sends report mail to … only |
An address under email: is outside the domains your workspace admin allows. |
Use an address of your company, or ask your workspace admin. |
Requirement name … matches project name |
uv refuses because the directory has the same name as a package. | Rename the project in pyproject.toml. |
several .qmd files … set entry |
The directory has more than one document. | Set entry: in velonde.yaml. |
app.py … found but none of shiny, streamlit, dash, fastapi, vetiver or fastmcp is imported |
Detection could not tell the kind. | Set type: in velonde.yaml. |
velonde.yaml: … |
The manifest is invalid. The message names the key. | Fix velonde.yaml. |
uses: mounts a pipeline's store … needs a ReadWriteMany storage class |
This workspace cannot share store volumes between pods. | Remove uses, or ask your workspace admin. |
502: could not resolve system dependencies |
The package manager API did not answer. | Retry. If it keeps failing, list system-packages by hand. |
403: app 'X' belongs to … |
Another user owns an app of that name. | Choose another name in velonde.yaml (--name on a first deploy), or ask the owner to add you as a maintainer. |
403: velonde.yaml changes maintainers … |
You are a maintainer, and your velonde.yaml lists other maintainers than the app has. |
Write the values from the message into velonde.yaml, and ask the owner to make the change. |
400: velonde.yaml: audience: external, but this workspace has no external apps server |
The workspace has no server for that audience. | Ask your workspace admin to add it, or remove audience. |
413: upload larger than 200 MB |
The directory contains large files, and the compressed upload exceeds 200 MB. | Move them out. |
exceeded quota on an app that will not start |
The workspace's quota is used up. | Ask your workspace admin. |
If an app builds, starts and then fails, it shows its error in the browser, and
velonde logs NAME prints what it wrote to its output (Logs). Reproduce the error
in your session first: run shiny::runApp(port = 3838) in one terminal and
curl -s http://127.0.0.1:3838/ in another, or run uv run shiny run app.py.
Work on an app as a team¶
The person who deploys an app first owns it. There are two ways for others to work on the same app.
Maintainers. The owner lists people by user id under maintainers in the app's velonde.yaml,
or groups under maintainer-groups, and deploys:
A maintainer can do with the app what its owner can do. They can deploy it and roll it back,
set its secret variables, see its history and the key of an API, run a pipeline and read its
logs, and bind the app to a repository or unbind it. Three things remain with the owner and
workspace admins: deleting the app, changing the two maintainer keys, and handing the app to another
owner with velonde owner, which also removes the maintainers. If a maintainer deploys a velonde.yaml whose maintainer keys differ from
the app's, the workspace refuses the deploy, so that the file and the app do not drift apart. The
maintainer then asks the owner to make the change.
The app keeps its owner when a maintainer deploys it. The pipelines under uses: must admit
the owner, and a pipeline's runs call APIs as the owner.
A shared repository. Bind the app to a branch with velonde git bind, as
Deploying from a repository describes. Every push to the branch deploys the app, so
the people who may push to the branch decide what runs, and they need no session on the workspace
to do it. The velonde commands on the app, such as velonde env set or velonde logs, remain with the
owner, the maintainers and admins. A push that changes the maintainer keys in velonde.yaml fails
to deploy, and velonde git status says why. The owner applies such a change by running
velonde git bind again.
To get the code of an app that a colleague owns, run velonde clone <app>, as
Working on an app's code together describes. That page also covers creating a
repository for a new project on your company's git server.
Anyone who can deploy an app can read its secrets, because the code they deploy runs with them. This applies to maintainers and to everyone who may push to a bound branch. List only people you would give the app's secret variables to.
Publish outside the company¶
By default an app is for the people who log in to the workspace. The audience key in velonde.yaml
publishes it to others. A workspace admin decides which audiences a workspace has, and each one has a host
name of its own.
audience |
Who can open it | Address |
|---|---|---|
internal (the default) |
The people who log in to the workspace | the apps host |
external |
The people who log in to the workspace's second login, typically your customers with accounts at their own identity provider | the external host |
public |
Anyone on the internet, without a login | the public host |
The deploy output ends with the address, and velonde apps shows the audience of every app. To
move an app to another audience, change the key and deploy again. Both servers involved
restart, which takes about a minute.
What changes with the audience:
- Users. An external app sees the users and groups of the second login, and
access-groupsnames those groups. One login can hold several of your customers, each as a group, so that every customer sees only their apps. A public app has no users: every visitor gets a random id that lasts for the visit, in the groupANONYMOUS, andaccess-groupshas no effect. - Shared containers. A public app serves ten visitors from one container and at most fifty
at the same time, unless
seats-per-containerandmax-userssay otherwise. Without such a limit, anyone could start containers until the workspace runs out of resources. Write the app so that one process can serve several visitors: keep per-visitor state inside the session, not in global variables. - Variables. An external or public app gets its own
.Renvironandvelonde env setvariables only. The variables an admin sets for every app reach internal apps. - APIs and MCP servers. An external API takes a token of the second login's identity provider or the API key. It does not know the workspace's users, so a colleague calls it with the key as well. A public API takes no key at all: anyone can call it, and the API sees no caller. Identity never crosses from one audience to another. An external app that calls an internal API needs that API's key, and an internal MCP server is the only kind that the workspace registers in your assistants.
Anyone who may deploy may publish to every audience the workspace has. The deploy that moves an app
to external or public asks you to confirm it, and so does a first deploy with either. Check
what an app shows before you make it public: a pipeline store under uses: and every query in the code reach
whoever opens it.
New projects¶
velonde new sales --template shiny in a terminal of an IDE session creates the directory sales
from one of the workspace's templates. In R, velonde::new_app("sales", template = "shiny") does the
same from the console, and in RStudio so does File > New Project > New Directory > Velonde project.
velonde new without a name lists the templates your workspace offers.
An R template needs R, so you create its project in RStudio or VS Code. You get an renv project
with the template's packages. A Python template needs uv, which every IDE has. You get a pyproject.toml and a uv.lock, with the packages installed into the
project's .venv. Both kinds of project come with a velonde.yaml and a git repository with a
first commit. On a workspace with AI assistants, the project also has a CLAUDE.md that tells the
coding agent how the project is laid out. --repo (repo = TRUE in R) also creates the
project's repository on your git server, as velonde git create does. The platform provides these
templates:
| Template | Language | Makes | Entry |
|---|---|---|---|
shiny |
R | Shiny app with bslib and box modules | app.R |
plumber |
R | HTTP API with plumber | plumber.R |
plumber2 |
R | HTTP API with plumber2, Posit's successor to plumber | plumber.R |
mcp |
R | MCP server: R functions as tools for Claude Code and Posit Assistant | tools.R |
quarto |
R | Quarto HTML report with parameters and _brand.yml |
index.qmd |
quarto-dashboard |
R | Quarto dashboard, static or with server: shiny |
index.qmd |
rmarkdown |
R | R Markdown HTML report | index.Rmd |
targets |
R | targets pipeline with a persistent store | _targets.R |
script |
R | R script that runs as a pipeline | pipeline.R |
package |
R | R package for the workspace's package repository, with tests | DESCRIPTION |
shiny-python |
Python | Shiny for Python app | app.py |
streamlit |
Python | Streamlit app | app.py |
dash |
Python | Dash app | app.py |
fastapi |
Python | HTTP API with FastAPI | app.py |
mcp-python |
Python | MCP server: Python functions as tools for Claude Code and Posit Assistant, with FastMCP | server.py |
quarto-python |
Python | Quarto HTML report with Python chunks | index.qmd |
notebook |
Python | Jupyter notebook, with a kernel of the project's environment registered under the project's name | analysis.ipynb |
script-python |
Python | Python script that runs as a pipeline | pipeline.py |
package-python |
Python | Python package for the workspace's package repository, with tests | pyproject.toml |
Your workspace may replace these templates or add its own, which appear in the same list. A template
of your workspace's own with a pyproject.toml is a Python template, any other an R template.