Verified Commit cd47309d authored by Agate's avatar Agate 💬

Added contribution documentation

parent 9ec47f1e
This diff is collapsed.
...@@ -15,282 +15,8 @@ We offer various rooms to discuss about funkwhale: ...@@ -15,282 +15,8 @@ We offer various rooms to discuss about funkwhale:
Please join those rooms if you have any questions! Please join those rooms if you have any questions!
Running the development version Contribute
------------------------------- ----------
If you want to fix a bug or implement a feature, you'll need Contribution guidelines as well as development installation instructions
to run a local, development copy of funkwhale. are outlined in `CONTRIBUTING <CONTRIBUTING>`_
We provide a docker based development environment, which should
be both easy to setup and work similarly regardless of your
development machine setup.
Instructions for bare-metal setup will come in the future (Merge requests
are welcome).
Installing docker and docker-compose
This is already cover in the relevant documentations:
Cloning the project
Visit and clone the repository using SSH or HTTPS. Exemple using SSH::
git clone ssh://
cd funkwhale
A note about branches
Next release development occurs on the "develop" branch, and releases are made on the "master" branch. Therefor, when submitting Merge Requests, ensure you are merging on the develop branch.
Working with docker
In developpement, we use the docker-compose file named ``dev.yml``, and this is why all our docker-compose commands will look like this::
docker-compose -f dev.yml logs
If you do not want to add the ``-f dev.yml`` snippet everytime, you can run this command before starting your work::
export COMPOSE_FILE=dev.yml
Building the containers
On your initial clone, or if there have been some changes in the
app dependencies, you will have to rebuild your containers. This is done
via the following command::
docker-compose -f dev.yml build
Creating your env file
We provide a working configuration file that is suitable for
development. However, to enable customization on your machine, you should
also create a .env file that will hold your personal environment
variables (those will not be commited to the project).
Create it like this::
touch .env
Database management
To setup funkwhale's database schema, run this::
docker-compose -f dev.yml run --rm api python migrate
This will create all the tables needed for the API to run proprely.
You will also need to run this whenever changes are made on the database
It is safe to run this command multiple times, so you can run it whenever
you fetch develop.
Development data
You'll need at least an admin user and some artists/tracks/albums to work
Create an admin user with the following command::
docker-compose -f dev.yml run --rm api python createsuperuser
Injecting fake data is done by running the fllowing script::
command="from import fake_data; fake_data.create_data($artists)"
echo $command | docker-compose -f dev.yml run --rm api python shell -i python
The previous command will create 25 artists with random albums, tracks
and metadata.
Launch all services
Then you can run everything with::
docker-compose -f dev.yml up
This will launch all services, and output the logs in your current terminal window.
If you prefer to launch them in the background instead, use the ``-d`` flag, and access the logs when you need it via ``docker-compose -f dev.yml logs --tail=50 --follow``.
Once everything is up, you can access the various funkwhale's components:
- The Vue webapp, on http://localhost:8080
- The API, on http://localhost:8080/api/v1/
- The django admin, on http://localhost:8080/api/admin/
Running API tests
To run the pytest test suite, use the following command::
docker-compose -f dev.yml run --rm api pytest
This is regular pytest, so you can use any arguments/options that pytest usually accept::
# get some help
docker-compose -f dev.yml run --rm api pytest -h
# Stop on first failure
docker-compose -f dev.yml run --rm api pytest -x
# Run a specific test file
docker-compose -f dev.yml run --rm api pytest tests/
Running front-end tests
To run the front-end test suite, use the following command::
docker-compose -f dev.yml run --rm front yarn run unit
We also support a "watch and test" mode were we continually relaunch
tests when changes are recorded on the file system::
docker-compose -f dev.yml run --rm front yarn run unit-watch
The latter is especially useful when you are debugging failing tests.
.. note::
The front-end test suite coverage is still pretty low
Stopping everything
Once you're down with your work, you can stop running containers, if any, with::
docker-compose -f dev.yml stop
Removing everything
If you want to wipe your development environment completely (e.g. if you want to start over from scratch), just run::
docker-compose -f dev.yml down -v
This will wipe your containers and data, so please be careful before running it.
You can keep your data by removing the ``-v`` flag.
Typical workflow for a merge request
0. Fork the project if you did not already or if you do not have access to the main repository
1. Checkout the development branch and pull most recent changes: ``git checkout develop && git pull``
2. Create a dedicated branch for your work ``42-awesome-fix``. It is good practice to prefix your branch name with the ID of the issue you are solving.
3. Work on your stuff
4. Commit small, atomic changes to make it easier to review your contribution
5. Add a changelog fragment to summarize your changes: ``echo "Implemented awesome stuff (#42)" > changes/changelog.d/42.feature"``
6. Push your branch
7. Create your merge request
8. Take a step back and enjoy, we're really grateful you did all of this and took the time to contribute!
When working on the front-end, any end-user string should be translated
using either ``<i18next path="yourstring">`` or the ``$t('yourstring')``
Extraction is done by calling ``yarn run i18n-extract``, which
will pull all the strings from source files and put them in a PO file.
Working with federation locally
To achieve that, you'll need:
1. to update your dns resolver to resolve all your .dev hostnames locally
2. a reverse proxy (such as traefik) to catch those .dev requests and
and with https certificate
3. two instances (or more) running locally, following the regular dev setup
Resolve .dev names locally
If you use dnsmasq, this is as simple as doing::
echo "address=/test/" | sudo tee /etc/dnsmasq.d/test.conf
sudo systemctl restart dnsmasq
If you use NetworkManager with dnsmasq integration, use this instead::
echo "address=/test/" | sudo tee /etc/NetworkManager/dnsmasq.d/test.conf
sudo systemctl restart NetworkManager
Add wildcard certificate to the trusted certificates
Simply copy bundled certificates::
sudo cp docker/ssl/test.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
This certificate is a wildcard for ``*.funkwhale.test``
Run a reverse proxy for your instances
Create docker network
Create the federation network::
docker network create federation
Launch everything
Launch the traefik proxy::
docker-compose -f docker/traefik.yml up -d
Then, in separate terminals, you can setup as many different instances as you
docker-compose -f dev.yml run --rm api python migrate
docker-compose -f dev.yml run --rm api python createsuperuser
docker-compose -f dev.yml up nginx api front nginx api celeryworker
Note that by default, if you don't export the COMPOSE_PROJECT_NAME,
we will default to node1 as the name of your instance.
Assuming your project name is ``node1``, your server will be reachable
at ``https://node1.funkwhale.test/``. Not that you'll have to trust
the SSL Certificate as it's self signed.
When working on federation with traefik, ensure you have this in your ``env``::
# This will ensure we don't bind any port on the host, and thus enable
# multiple instances of funkwhale to be spawned concurrently.
# This disable certificate verification
# this ensure you don't have incorrect urls pointing to http resources
.. include:: ../CONTRIBUTING
...@@ -19,6 +19,7 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in ...@@ -19,6 +19,7 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in
api api
upgrading upgrading
third-party third-party
changelog changelog
Indices and tables Indices and tables
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment