Publishing & sharing your app

Publishing uploads your app's source code to the VIKTOR platform and places that version on a delivery line, which determines who runs it. Your source code is secure and cannot be inspected by users that have access to the online VIKTOR environment.

note

Free-tier VIKTOR developers (cloud.viktor.ai) can only publish editor-type apps with a public visibility on the app instance.

Testing and production versions

Each app has two delivery lines, and each line points at exactly one version of your app:

Line	What runs it	What it is for
Testing	Testing apps	For checking a version before release, reviewing, and user acceptance testing
Production	Project apps	The version your end users work with

You set each line separately. Publishing to testing leaves the production version untouched, so you can push a version out for testing without changing what your projects run. Releasing to production is a deliberate choice.

Testing always reflects the latest published version. Production is independent and can stay on an older version until you decide to release; it can never point at a newer version than testing.

note

A testing app is not the same as the development workspace described in the starter guide. The development workspace shows the code you are running locally while you build the app. A testing app runs a published version: the one the testing line points at.

You can move the production line to another version afterwards, including an older one, from the versions tab of your app. See Version history.

Publish a new app

There are two ways to develop and publish apps on the VIKTOR platform:

• App Builder: A fully in-browser development experience with AI assistance. You can develop and publish apps directly from your browser without any local setup.
• Local development with CLI: The traditional approach using your local development workspace and the VIKTOR CLI (described below).

To make an app available for others to use, you will need to follow these two steps:

1. Publish the application source code
2. Add the app to a project

note

It might be the case that your company doesn't allow users to create projects themselves. In this case you need to ask the environment administrator to create a project for you.

The following sections describe the local development publishing flow using the CLI. If you're using the App Builder, you can publish directly from the browser by clicking the Publish button.

1. Publish the application source code

Once your app is ready, the developer can publish the source code by using the publish command of the CLI:

viktor-cli publish

You can also override the tag and app name of your new published version by running the CLI command such below:

viktor-cli publish --registered-name <insert-app-name-here> --tag v0.1.0

The registered-name is specified when the app is created by the developer and can be inspected using the apps command of the CLI:

>>> viktor-cli apps
The following apps are connected to your account:
Name            | Full name                   | Latest tag | SDK version | Status
crane-demo      | crane-demo.viktor.demo      | v2.1       | 13.6.2      | published
monitoring-demo | monitoring-demo.viktor.demo | v1.1       | 13.6.1      | published
...

Alternatively, find your app on the Develop page and navigate to the app details page.

note

• Although we use the term 'tag' as a variable for the publish command, this is not linked to the git tag. The CLI will not check out the tag you specify in the publish command, you will have to do this manually first (e.g. git checkout <TAG>).
• If you are using git the CLI respects the .gitignore file and uses git to gather the files for uploading to VIKTOR.
• You can force the CLI to upload all files in the app folder by using the --use-filesystem flag.
• If you have any uncommitted changes or unstaged files, the publish command will fail as a safety mechanism.

Choose where a version goes

By default, viktor-cli publish sends the new version to both the testing and the production line. To publish to testing only and leave the production version untouched, add the --skip-production flag:

viktor-cli publish --skip-production

Use this when you want to try a version out in a testing app before your end users get it. Once you are satisfied, point the production line at that version from the versions tab, described in Version history.

If you publish from the browser instead, the Publish dialog offers the same choice. See Publishing in the App Builder guide.

tip

In a CI/CD pipeline, use the same flag on viktor-cli ci-publish so that an automated build does not release to production on every commit. See Continuous deployment.

Excluding files from publication

You can exclude specific files and directories from publication by creating a .viktorignore file in your app's root directory. This is useful for keeping development-only content out of your published app, such as:

• Test files and directories
• Documentation
• Log files
• Data files
• Build artifacts
• IDE configuration files

The .viktorignore file uses the same syntax as .gitignore:

.viktorignore

# Exclude test directories and files
tests/
test_*.py

# Exclude documentation
docs/
*.md

# Exclude log and data files
logs/
*.log
*.csv

# Exclude IDE files
.vscode/
.idea/

Pattern syntax:

• directory/ - Exclude a directory and all its contents
• *.log - Exclude all files with .log extension
• data/**/*.tmp - Recursively exclude files matching the pattern
• # comment - Lines starting with # are ignored

caution

Do not exclude files that are required for your app to run, such as:

• app.py or your main application file
• requirements.txt or dependency files
• viktor.config.toml configuration file
• Source code directories containing your app logic
• Any modules imported by your application

Excluding critical files will cause your app to fail during publication or at runtime.

tip

The .viktorignore patterns work in addition to .gitignore. Files excluded by either will not be published.

After pressing enter you will see a spinner which you can use to monitor the publish process. Once you see the spinner it is not possible to cancel the process. It is not a problem if you accidentally close the CLI at this point, publishing will continue in the background. During publication several checks will be performed. If any problems occur you will be presented with the reason for failure. Please contact VIKTOR in case you are stuck.

2. Add the app to a project

Once your app is published (either via the App Builder or CLI), you need to add it to a project to make it available for use. To do this:

1. Navigate to the projects page
2. Click the Create project button (if the desired project doesn't exist yet)
3. Click the Add app button
4. Select the desired app from the list
5. Click Add to project

The app is now added to the project and can be used by project members.

note

In case your company does not allow users to create projects, you will need to contact your environment administrator to create a project for you before you can add your app.

Publish a new version of an existing app

Every new addition or change to the application source code requires a new release, which is done by directly publishing the source code. Publishing a new version can be automated using Continuous Deployment (CD) tools.

Make sure to keep backward compatibility in mind when creating new releases.

caution

In case of an entity type incompatible publish, follow these steps:

1. Use the publish command with the new app code
2. Wait for it to fail due to the incompatible change
3. Notify your contact person at VIKTOR (or send a message to support@viktor.ai) and mention the incompatible change(s)
4. Await VIKTOR to republish with necessary adjustments in the database

Move a line to another version

Publishing is not the only way to change what runs where. From the versions tab of your app you can point the production line at any other version in the list, including an older one. The test app always reflects the latest published version and cannot be moved to an older one. Moving production to an older version is how you return it to a known-good state when a release turns out to be broken, instead of having to fix forward.

VIKTOR validates the change at the moment you confirm it and refuses it when the two versions are not interchangeable, for example when the app type differs or when the change does not meet the backward compatibility rules. You are told the specific reason, so you can decide what to do next. When a change would delete stored data, you have to accept that explicitly before it is applied.

For the steps, see Version history.

Limitations

The following cases cannot be handled without intervention from VIKTOR. If you want to publish an app and encounter one of these limitations, please reach out to your contact person at VIKTOR to publish the application.

• It is not possible to clear the database of an app before publishing.
• It is not possible to publish an app that has incompatible entity type changes, e.g:
  • Removal / renaming of entity types that are already present in the database
  • Changing names of top-level entities

The same entity type rules apply when you point a delivery line at a different version, not only when you publish. A version change that would remove an entity type already present in the database is blocked at the moment you confirm it.

FAQs

Why do my end users not see the new version after publishing?

Most likely the version went to testing only. Project apps run the production version, so a publish with --skip-production, or a browser publish that targets testing alone, leaves them on the previous version. Open the versions tab of your app and point the production line at the new version.

A version that has just been released also takes time to reach every app, and the versions tab shows this while it is in progress. On an app with many project apps this is normal and is not a failure.

Can I go back to an older version?

Yes. You can deploy to an older version from the versions tab. VIKTOR validates the change when you confirm it, so a version that is not interchangeable with the current one is refused with the reason. See Move a line to another version.

Why is my version change blocked?

The two versions are not interchangeable. The usual causes are a different app type, a deprecated or unsupported SDK or Python version, an entity type that exists in one version but not the other, or app variables that the other version needs and your app no longer has. VIKTOR names the specific cause when it refuses the change.

App variables are not part of a version, so keeping them aligned with the version you select is your responsibility. See using environment variables.