Getting started

This part of the documentation provides a first steps guide for quickly setting up an application with ViUR. The following chapters will go much deeper into ViUR, its architecture and how it is used. The Google App Engine™ is only introduced shortly here. Knowledge on what it is, how it works and how an application is registered there is required before continuing.

Prerequisites

ViUR runs on top of the Google App Engine (GAE) platform for the Python Standard Environment. This means, that a ViUR application has to be deployed to a project in the Google Cloud Platform when it is run on the internet.

Before you start your first ViUR project, make sure that at least the first of the following prerequisites are installed on your system.

Note

We strongly recommend to use a POSIX-like operating system like Linux or Mac OS for developing ViUR applications.

Getting ViUR to run properly on Microsoft Windows is a nightmare for several reasons. The only well-working solution to use a Windows system for ViUR development is when Windows Subsystem for Linux is used - otherwise, forget about it. A tutorial to set it up is available at VIUR3 on Windows

Python & pip

Since ViUR is a framework written in pure Python, it requires a Python interpreter to be installed. ViUR currently only runs with Python 3.10+ and upwards, so this must be installed on your system.

Pip, the Python package installer, is also a necessary feature to develop applications with ViUR.

gcloud SDK

For the deployment as well as a local development and testing environment, Google offers the gcloud SDK for Python.

Download and install the gcloud SDK natively from the above location for your platform. Mac OS, Linux and Windows are supported. In case that Linux is used, your favorite package manager should be consulted first, maybe it already supports packages for the gcloud SDK.

Note

For now, Google offers its “Python Standard Environment” that ViUR is using only for Python 3.10+.

After you successfully installed the gcloud SDK, make sure that you install the following components:

  • app-engine-python

  • app-engine-python-extras

  • cloud-datastore-emulator

To install all required gcloud components, just run

gcloud components install app-engine-python app-engine-python-extras cloud-datastore-emulator
Image showing the output of 'gcloud components list'

This is how gcloud components list should look like.

Further prerequisites

For a full ViUR development environment, the following components must also be installed and made available on your system:

  • Pyodide

  • {less} is a compiler for a better CSS-dialect. It is also required to build ViUR’s

    web-based administration interface vi, but also by our design- and UI-framework ignite

  • In most cases it is required to install npm to get {less} and build-systems

    like gulp to work, which is also used by ignite.

Starting a ViUR project

For a professional project setup, we recommend to use our pre-configured base repository. This repository can be used for a ViUR project setup that prepares the required ViUR modules like viur-core, vi-admin and ignite as dependencies into the repository.

Cloning the base repository

Simply clone the base repository and afterwards run clean-base.py to obtain a stand-alone repository which can immediately be executed or pushed wherever you like.

These are the commands to be executed in a shell:

# Clone base repository into a project folder
git clone https://github.com/viur-framework/viur-base.git hello-viur

# Change into new project folder
cd hello-viur

# Run clean-base.py
./clean-base.py
Image showing the output of the steps done to clone the ViUR base repository

Cloning and setting up the ViUR base repository for a new project.

First startup

When the above steps where initially performed, you can _locally_ start your application. For this case, the gcloud SDK offers the program dev_appserver.py. This program can be used to emulate a Google App Engine standard environment on the local development computer and is perfectly suitable for creating the data model and basic functionality.

You can either start dev_appserver.py with its particular parameters by hand, or use the script local_run.sh which is generated from the clean-base.py run above.

./local_run.sh
Image showing the output of the steps done when starting ``dev_appserver.py``

First local start of the new ViUR application.

When the output on your console looks like above, fire up your favorite web-browser and open http://localhost:8080. You should see a warm welcome from your ViUR project!

Display of the generated welcome page on http://localhost:8080

Welcome to your new project!

Logging in

On the first startup, ViUR creates an new admin-user named admin@<your-app-id>.appspot.com with a random password for you. This password is printed to the server’s debug console, where you have to copy it out.

Watch out for a line that looks like this:

ViUR created a new admin-user for you! Username: admin@hello-viur.appspot.com, Password: SU7juUIb1F2aZ

When the system is started in the cloud for the first time, an e-mail with this password is sent to all application administrators.

Alternatively, you can login with a simulated Google user. Both login forms are provided by the default server and can be done using the Vi.

What’s next?

When you came to this point, you’re ready to start with the basic concepts and do first steps in developing your project.