Building¶
There are some documented ways in how to setup your development or deployment environment for this project:
- Using a CI/CD system such as GitLab CI/CD.
- Using Docker and Docker Compose.
- Using GitLab Runner.
- Using PyEnv.
- Setting up your environment manually.
They are explained in the following sections, and of course you can also proceed with your own procedure if nothing else fits. They're tested with Debian-like operating systems.
The procedures can also be executed inside a virtual machine, preferably using Debian.
Environment file¶
The LEKTOR_*
and other environment variables can be stored in the .env
configuration file.
Helper scripts¶
Also, number of helper scripts are available to aid development, testing and deployment:
scripts/provision-docker-compose
: installs Docker Compose in a Debian-based system.provision-gitlab-runner
: installs GitLab Runner in a Debian-based system.provision-pyenv
: install PyEnv locally at user's$HOME/.pyenv
.provision
: setus up the basic system environment (system-wide packages).env
: sets up the basic Python environment needed to build the landing pages (local Python packages).build
: the actual build script.build-with-gitlab-runner
: build the landing page using GitLab Runner.server
: wrapper around lektor server.server-public
: basic HTTP server used to inspect build artifacts stored at thepublic/
folder.
Using a CI/CD system such as GitLab CI/CD¶
For GitLab CI/CD we provide two configurations:
- .gitlab-ci.yml: the standard CI/CD used when the project is hosted at https://gitlab.torproject.org.
- .gitlab-ci-deployment.yml: the CI/CD configuration when the repository is hosted in other GitLab instances.
Using Docker and Docker Compose¶
Make sure you have Docker and Docker Compose properly installed. The provision-docker-compose script serves as an example in how to do that.
Then proceed as usual:
docker-compose up
This should build the container image and bring a service container running
lektor server
with a HTTP server listening at http://localhost:5000.
As an alternative, it's possible to use the provided Dockerfile for serving a statically built landing page.
Using GitLab Runner¶
Note
This method has been deprecated.
The GitLab Runner approach is aimed to test the CI configuration for deployment directly through a GitLab Runner instance locally installed in your computer.
Install GitLab Runner according to the docs or using the provided provision-gitlab-runner script.
Then proceed running the corresponding build script:
scripts/build-with-gitlab-runner
If the build is successful, the resulting site will be available at the public/
folder
and can be browser using a HTTP server such the one provided by this repository which
listens on http://localhost:5000:
scripts/server-public
Using PyEnv¶
Another approach is to use PyEnv to setup your environment with the required Python version needed to build the landing page.
The provision-pyenv script has an example in how to do that, which should run after the provision script.
scripts/provision
scripts/provision-pyenv
Then you can simply use the provided build script:
scripts/build
You can also manually invoke Lektor like this:
source scripts/env
lektor clean --yes
lektor server
The virtualenv is created by default inside of your $HOME/.virtualenvs
folder, but that can be customized with the $VENV
shell environment variable.
Setting up your environment manually¶
You might use this approach if you prefer a customized way to install the required Python version and/or you already have your own Lektor workflow.
First install the required Python version, whose exact number can be found in the Dockerfile or at the .gitlab-ci-deployment.yml file.
A suggested way is running this command sequence:
lektor-venv && source .env && lektor clean --yes && lektor server
where lektor-venv
is a bash function that sets up a venv
, and .env
is
literally just a file exporting the LEKTOR_*
environment variables:
lektor-venv ()
{
VENV="${VENV:-$HOME/.virtualenvs/onion-launchpad}
[ -d "$VENV" ] && source "$VENV/bin/activate" && \
echo 'virtualenv found in "$VENV" and activated' && return;
python3.8 -m venv "$VENV" && source "$VENV/bin/activate" && \
pip install --upgrade pip lektor && echo 'virtualenv set up in "$VENV" and activated'
}
Make sure to:
- Replace
python3.8
with the required Python version, if needed. - Set the
$VENV
shell environment variable according to your preference.