Development¶

If you are familiar with Django or Vue (or want to learn!) and are interested in getting involved, please don’t hesitate to get in touch!

For guidelines how to contribute, please first read the Contributing guide.

NOTE! Due to bugs in the GitLab -> Codeberg migration tool, old issues before October 2024 can only be found in the old [GitLab issue tracker](https://gitlab.com/jaywink/socialhome/-/issues).

NOTE! These instructions are for the backend codebase, pelase see the frontend repository for frontend side development.

Backend environment setup¶

Python Virtualenv¶

Python 3.10 is the suggested minimum development version. Ensure the following are installed:

Python system dependencies
PostgreSQL server
Redis

The file requirements.apt contains other various dependencies. You can use the install_ubuntu_dependencies.sh script to help installing these.

You can use the install_alpine_dependencies.sh script to install required dependencies (including Python, NodeJS, PostgreSQL and Redis) on Alpine.

To generate profiling SVG’s with pytest, also install the graphviz package (for example from apt), which provides dot.

Install Python dependencies¶

We use pip-tools as the way to install Python dependencies. All the “base” dependencies, including production deployment dependencies are locked in requirements.txt. The file dev-requirements.txt includes both the base and the extra development/testing related dependencies.

To use pip-tools, first install it:

# Ensure pip and setuptools are up to date as well
pip install -U pip pip-tools setuptools

Then install dependencies:

# Production environment
pip-sync

# Development environment
pip-sync dev-requirements.txt

It is not mandatory to use pip-tools for running a production installation. For development it is mandatory. All dependencies should be placed (unlocked) in either requirements/requirements.in (base) or requirements/requirements-dev.in (development extras). Then execute ./compile-requirements.sh to update the locked dependency files after each change to the .in files. See pip-tools for more information.

Configure¶

Configuration is done via environment variables. For the meaning of them, look them up under files in config/settings. Values in the file .env will be used automatically.

cp .env.example .env

Edit any values necessary. By default the SECRET_KEY is empty. You MUST set something to it. We don’t supply a default to force you to make it unique in your production app.

Create a database¶

Docker¶

The easiest way to run a database is using Docker. Install Docker and then use the following command:

docker run -e 'POSTGRES_PASSWORD=socialhome POSTGRES_USER=socialhome POSTGRES_DB=socialhome' \
    --name socialhomedb -d -p '5432:5432' postgres
# Create the user and database
docker exec -ti -u postgres socialhomedb createuser -s -P socialhome  # give password 'socialhome'
docker exec -ti -u postgres socialhomedb createdb -O socialhome socialhome
# Migrate the database
python manage.py migrate

Later to start the same container just do:

docker start socialhomedb

System¶

For example on Ubuntu:

sudo su - postgres
createuser -s -P socialhome  # give password 'socialhome'
createdb -O socialhome socialhome
exit
python manage.py migrate

Install Redis¶

Either use system Redis (for example on Ubuntu sudo apt install redis-server) or use Docker:

docker run --name socialhomeredis -d -p '6379:6379' redis

To later start it:

docker start socialhomeredis

Running the development server¶

Just use the standard command:

python manage.py runserver

Unfortunately runserver_plus cannot be used as it does not integrate with Django Channels.

Running the Django shell¶

It is recommended to use the enhanced “shell plus” provided by Django Extensions package which is automatically installed via the development dependencies. One of the benefits is that it will automatically import all project models.

To launch the shell:

python manage.py shell_plus

Creating a user¶

To create an superuser account, use this command:

python manage.py createsuperuser

After this you need to log in once with the user via the user interface (which creates an email confirmation) and then run the following in the Django shell to confirm the email:

from allauth.account.models import EmailAddress
EmailAddress.objects.all().update(verified=True)

You should now be able to log in as the user admin.

Search index¶

The search indexes must be initialized, otherwise there will be an error when trying to use search. Run this command once:

python manage.py rebuild_index

Any further changes to indexes objects will be maintained automatically from this point onwards. If you ever need to rebuild the index from scratch, use the same command.

Running tests¶

The user needs right to create databases:

# On some distributions, regular users are not sudoers; you may need to type:
#    su -
su - postgres
psql -c "ALTER USER socialhome CREATEDB;"

Python tests¶

py.test

To also generate profiling information, add --profile --profile-svg to the command.

Building local documentation¶

cd docs
make html

Doing a release¶

Bump version number in three places:

socialhome/__init__.py
docs/conf.py
docs/changelog.rst

To generate a markdown version of the release changelog, first install Pandoc:

sudo apt install pandoc

Then execute the following and copy the markdown version for pasting to Codeberg releases or a Socialhome post:

pandoc --from rst --to markdown_github docs/changelog.rst | less

Make a tag¶

Create a git tag for the release, ie git tag v<version>.

Push the tag and master branch.

Docker images¶

Publish a new Docker image by running ./multiarch_release v<version>.

Start new development cycle¶

Set a development version in the same above files. This is basically the next minor release postfixed by -dev.

Commit and author stats¶

Some commands to get nice stats for release posts.

Authors

git shortlog -s -n -e <first release commit>..HEAD --no-merges

Changes

git diff --stat <first release commit>..HEAD

Generating dummy content¶

There is a management command to generate a bunch of dummy Content objects. Please feel free to expand it with more configuration options and different types of content. To use it, run the following:

python manage.py create_dummy_content

--help will give you available options.

Contact for help¶

See our communication channels in the Community page.

You can also ask questions or give feedback via issues.