Quickstart Tutorial

How to set up a client/server application

This tutorial shows how to set up a simple client/server application using Phovea.
The name of the example application is "Test" but you can name it as you like of course.

Install the phovea-generator

 npm install -g yo
 npm install -g github:phovea/generator-phovea

Create application repository

Create repository for application. The application repository is the place where the whole application code resides.

  1. Go to github.com and create a new repository. Name the repository "test". Don't create a README.
  2. Clone it locally: Open a terminal and enter: git clone https://github.com/<username or organization>/test.git

Create a product repository

  1. Go to github.com and create a new repository. Name the repository "test_product". The _product suffix is important so that Phovea knows that it is a Product. Don't create a README.
  2. Clone it locally: Open a terminal and enter: git clone https://github.com/<username or organization>/test_product.git

Initialize application

cd test
yo phovea:init-app

Follow the wizard

Application Title: Test
Client Only: N
Add nesessary libraries
Plugin name: test
Description: A simple test application
Leave all other fields as they are (just press Enter)

Switch to development branches

In package.json, change under dependencies all phovea references to develop branch.

"phovea_core": "0.1.0" -> "phovea_core": "github:phovea/phovea_core#develop"
"phovea_ui": "0.1.0" -> "phovea_ui": "github:phovea/phovea_ui#develop"

Commit changes

git add .
git commit -m "Initial commit"
git push

If you now go to your Github Test repository, you should see the project the project files and a Readme that explains the installation process.

Create development branch

Stay in the test folder and enter following commands:

git checkout -b develop
git commit -m "New development branch"
git push --set-upstream origin develop

Initialize product

cd test_product
yo phovea:init-product

Follow the wizard

Plugin name: test_product
Description: A test product
Leave project homepage and author's credential as they are
Service type: Web
Service name: Testservice
Primary respository: <username or organization>/test
Primary repository branch: develop
Additional plugins: ENTER
Add custom additional plugins: N
Add another service: y
Service type: Rest-API
Service name: test_server
primary repository: phovea/phovea_server
primary repository branch: develop
Add custom additional plugin? N
Add another service? N

Commit changes

git add .
git commit -m "Initial commit"
git push

Setup Workspace

Create new folder named workspace and switch to it.

cd ..
mkdir workspace
cd workspace

So the test, test_product and workspace should be on the same level.

Use phovea generator to create workspace

yo phovea:setup-workspace <username or organization>/test_product
SSH clone: No

Create server side

mkdir testserverplugin
cd testserverplugin
yo phovea:init-app-slib
cd ..

Clone and resolve the phovea_server

yo phovea:clone phovea_server
cd phovea_server
git checkout develop
cd ..

The directory structure should look like this now:

  • workspace
    + test
    + phovea_server
    + testserverplugin

Create workspace

In the workspace folder, do:

yo phovea:workspace

Create REST endpoint

cd testserverplugin
yo phovea:add-extension
# Base Type: server type: namespace, id: hello-rest, filename: hello_rest
# extras: namespace=/api/hello_rest

Start docker

In the workspace folder, do:

docker-compose up

Keep this shell open all the time since the docker process is running in it. If you want, you can also run docker as a demon:

docker-compose up -d

In this case, you can close the shell after you entered the command.


  • For docker, you need hardware virtualization enabled.
  • If you encounter the following error under Windows: _ERROR: for <test_api_1> Cannot create container for service api: Drive has not been shared _ Click on the whale symbol in the taskbar -> Settings -> Shared Drives -> Enable

Start Webapplication

cd workspace\test
npm run start:test

Open PyCharm and open the project which is located in workspace.
You can delete the test and test_product folders, since the whole application code is available in the workspace folder. Modify/extend you project as needed and commit your changes to the github repository.

Open Chrome (or any other webbrowser), enter localhost:8080. This is the root page. If you enter localhost:8080/api/hello_rest, you should get the message "Hello World" as JSON string.


  • You can commit directly from your Pycharm IDE by pressing STRG+K