How to run an application on your local system¶
This guide describes how to start from the GitLab page for a web application and get to the point where you can access a local instance in your browser and run tests locally.
This guide is appropriate for applications which do not have a
compose.sh file in the root
of the repository. See the older reference guide if that
file is present.
If you have not already done so, make sure you have followed our how-to guide for preparing your
system and installed the software which it recommends. You should confirm
poe commands are present on your
PATH and that the
compose plugin is installed.
Downloading the application¶
git clone to clone the application repository to your machine. Change to the directory
containing the application using
Running the application¶
README.md file for any application-specific bootstrap steps. Commonly these will
take the form of copying a
secrets.env.in file provided in the repository to a file named
secrets.env and providing secret values. The
secrets.env.in file should provide
README.md file doesn't include something which you later find out is required for
bootstrapping, open an issue and, if you feel comfortable, a merge request
adding the missing information.
You may be used to manually creating a virtualenv for Python projects in a directory named
.venv. Do not do this. Instead, let the
poetry tool create a local Python virtualenv for the
application and install dependencies:
What is a "virtualenv" and what does "poetry install" do?
We cover this in the explainer document about our webapp boilerplate.
Check that the test suite passes:
poetry poe pytest:local
poe command to
poetry runs one of a predefined set of "tasks" within the virtualenv. You can
see the list of tasks in the
If you have installed
poe into your
PATH, you can also use
poe pytest:local as a shortcut.
You can see all the "poe" tasks by running
poetry poe with no other arguments.
Start the application:
poetry poe up --wait
--wait flag is passed to
docker compose and tells docker to wait until all the containers
have started and return control back to you.
up task is a convenient way of running the
docker compose --profile development up
command. You could have also started the application via
docker compose --profile development
up --wait if you wanted to exercise your fingers with extra typing.
Examine the logs from the application:
docker compose logs --follow webapp
Visit http://localhost:8000/ in your browser to access the application.
In this guide you learned how to clone one of our applications locally, run tests and start the application.
- Read more about what you can do with our webapp developer environment in the reference guide.