This page documents how to get the GeniePy boilerplate up and running for a new project.
Download
Purchase the boilerplate from Gumroad.
After the purchase, you'll be able to download an app-XX.YY.ZZ.zip
file to your
machine. This is the base for setting up a new application.
Note that the XX.YY.ZZ
in the file name will be different depending on the
version you end up purchasing. Once you've made a purchase, all future versions
will be made available to you at no additional cost.
Extract
As the artifact is a zip
file, you need to extract it in the directory where
you want to initialize the project.
Assuming that you store your work projects under $HOME/projects
and the name
of your new SaaS is GeniePy
, the following commands should set everything up.
# create the project directory
$ mkdir -p ~/projects/geniepy
$ cd ~/projects/geniepy
# move and extract the downloaded file into the target directory
$ mv /path/to/app-22.01.01.zip .
$ unzip app-22.01.01.zip
# cleanup
$ rm app-22.01.01.zip
This should extract the application source code into the current working directory.
Configure
In line with the 12-factor methodology, GeniePy uses environment variables for application configuration.
We use the env_file
configuration option to set the environment variables
for the main server process. Make a copy of the sample.env
file included in
the codebase,
$ cp sample.env .env
... and edit the contents of this new file based on what your project needs.
All the available settings are defined under app/settings.py
. If you'd like to
see what else is available, this is the file you should refer to.
Prepare
Please note that you'll need to have a working installation of Python available for this section to work. For more details please refer to the Python pre-requisite.
Prepare a virtualenv in the current directory. The recent versions of Python
make this easy using the in-built venv
module.
$ python -m venv venv
$ source venv/bin/activate
If you'd like to set up the virtual environment a different way, pyenv is a good option to consider, especially if you're working a lot with Python codebases.
Run
Run make init
, which will install the latest version of pip
, pip-tools
,
and invoke
, all three of which are Python dependencies that GeniePy uses. This
command will also initialize the Docker containers for local use.
Next, run invoke alembic.upgrade
, which will run all the database migrations
to set up the database tables.
Finally, run invoke app.server
in the terminal.
That's it! You should now be able to visit the application in the browser at
http://localhost:9001
.
Lint
Run invoke test.lint
in the project directory.
At the time of this writing, the project's code is linted using three tools:
flake8
, black
, and isort
.
flake8
is used to ensure quality checks on Python codebases. It can point out
issues related to style (eg. if some code is not conformant to PEP-8) or for
discovering errors that would otherwise only be discovered at runtime (eg.
undefined variables).
black
is a code formatter for Python. If you've worked in a team of software
developers, you've most likely ran into formatting issues at one time or
another. black
puts an end to such discussions by choosing a formatting style
for you.
isort
is responsible for sorting imports in Python code. This keeps the
topmost section of the file clean and consistent across the entire codebase.
These three tools have also been installed as pre-commit
hooks. If you set up
pre-commit
as described in the previous section, all these linters will run
sequentially whenever you run git commit
. Any violations will prevent you from
committing code.
Test
Run invoke test.pytest
in the project directory.
This should run all the database migrations on the test database and then run
the entire test suite using pytest
.
pytest
is an excellent framework for writing better tests in Python. It is
widely used in the Python community and has a rich plugin system which end-users
can benefit from.