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
Further prerequisites¶
For a full ViUR development environment, the following components must also be installed and made available on your system:
Pyodide
- 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
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
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!
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.