Tutorial

This tutorial will demonstrate using WebLodge to deploy a simple application.

Standard application

Here is the application we will deploy:

$ # The application entry point.
$ cat app.py
from flask import Flask

app = Flask(__name__)  # The Flask application.

@app.route("/")
def hello_world():
   return "<p>Hello, World!</p>"

$ # The application dependencies.
$ cat requirements.txt
Flask

You can Deploy this application by executing the following commands in a terminal:

$ # Install WebLodge.
$ pip install weblodge

$ # Build the application.
$ weblodge build
$ weblodge deploy
...
The application will soon be available at: https://weblodge-tutorial.azurewebsites.net

$ # But you can also build and deploy the application in a single command.
$ weblodge deploy --build
...
The application will soon be available at: https://weblodge-tutorial.azurewebsites.net

During the build phase, WebLodge will create a folder with the application built and other files needed to deploy the application. This private folder does not need to be versioned and ignored by your version control system.

WebLodge will create a .weblodge.json file containing the application’s deployment configuration during deployment. This file can be version control. The application needs a subdomain on the internet – here weblodge-tutorial –. This subdomain is unique on Azure. You can set it by passing the –subdomain option. Otherwise, WebLodge will generate one.

After a few seconds, the application will be available at the given subdomain and accessible from your browser.

Note

The .weblodge.json contains the subdomain of the application. This subdomain is unique on Azure. However, another application might already use, making it unavailable. If this is the case, you can change the subdomain in the .weblodge.json file and redeploy the application.

Warning

By default, WebLodge will deploy free resources. This means Azure will shut down the application after a couple of minutes of inactivity, and the usage will be limited daily. You can change this behaviour by passing the –sku option. Azure limits the number of free applications. If you encounter that problem, please remove the previously created resources or deploy and change the –sku option.

Adding environment variables

Your application may use environment variables containing dynamic values or secrets. For example, we can update the app.py file to return a message that depends on the MESSAGE environment variable:

$ cat app.py
import os
from flask import Flask

app = Flask(__name__)  # The Flask application.

@app.route("/")
def hello_world():
  return f"<p>Hello, {os.environ['MESSAGE']}!</p>"

By default, WebLodge will see if the .env file exists, and if so, use it for environment variables. You can also specify this file by using the –env-file option:

$ cat .env
MESSAGE=World
$ # Deploy the application using the `.env` file.
$ weblodge deploy
...
The application will soon be available at: https://weblodge-tutorial.azurewebsites.net
$ curl https://weblodge-tutorial.azurewebsites.net
Hello, World

$ cat .prod
MESSAGE=Guido
$ # Deploy the application using the `.prod` file.
$ weblodge deploy --env-file .prod
...
The application will soon be available at: https://weblodge-tutorial.azurewebsites.net
$ curl https://weblodge-tutorial.azurewebsites.net
Hello, Guido

Note

Environment variables are defined during the deployment phase. You don’t need to rebuild the application to change them.

Behind the scene, WebLodge uses the python-dotenv package to load the environment variables. Feel free to use its features.

Adding continuous deployment

Note

This feature is only available for GitHub repositories.

Using GitHub Actions, you can automatically deploy your application when you push to your repository.

You can setup the infrastructure and components by executing the following commands in a terminal:

$ # Create the GitHub workflow file.
$ weblodge github --username <your-username> --repository <your-repository> --branch <target-branch>
Please, add the following secrets to your GitHub repository:
  - AZURE_CLIENT_ID: xxxxxxxxx-xxxx-xxxx-xxxxx-xxxxxxxxxxxx
  - AZURE_TENANT_ID: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  - AZURE_SUBSCRIPTION_ID: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Then, commit and push the following files:
  - .github/workflows/weblodge.yml
  - .weblodge.json
More information: https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository

Add the AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID as GitHub secrets. Then commit and push files .github/workflows/weblodge.yml and .weblodge.json. Your application will automatically be deployed on the next push on the target branch.

More information on the command GitHub.

Note

In this scenario, environment variables are not yet supported.

Deleting the infrastructure

You can delete the previously deployed infrastructure by executing the following commands in a terminal:

$ # With the validation prompt.
$ weblodge delete
Do you want to delete the application 'weblodge-tutorial' (yes/no.)?

$ # Without the validation prompt.
$ weblodge delete --yes