Skip to main content

Publishing & sharing your app

Publishing (also called "releasing" or "deploying") means that the application is uploaded to the VIKTOR platform, making the app available in the organization environment. Note that the 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 workspace.

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 environment 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 in the App store 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.

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 as described in step 1 in the section above. 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

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