novaburst/funquail
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Clean up documentation

Browse source
This commit is contained in:
Ciarán Ainsworth 2022-10-26 22:07:02 +02:00 • committed by Georg Krause
commit dfa73631c7
16 changed files with 836 additions and 1014 deletions
Download patch file Download diff file Expand all files Collapse all files

204
docs/developer_documentation/setup/docker.md
View file

@ -1,8 +1,202 @@
# Develop using Docker
```{include} ../../../CONTRIBUTING.md
---
start-after: "### Docker"
end-before: "### Vite"
---
Funkwhale can be run in Docker containers for local development. You can work on any part of the Funkwhale codebase and run the container setup to test your changes. To work with Docker:
1. [Install Docker](https://docs.docker.com/install)
2. [Install docker-compose](https://docs.docker.com/compose/install)
3. Clone the Funkwhale repository to your system. The `develop` branch is checked out by default
::::{tab-set}
:::{tab-item} SSH
```sh
git clone git@dev.funkwhale.audio/funkwhale/funkwhale.git
cd funkwhale
```
:::
:::{tab-item} HTTPS
```sh
git clone https://dev.funkwhale.audio/funkwhale/funkwhale.git
cd funkwhale
```
:::
::::
## Set up your Docker environment
````{note}
Funkwhale provides a `dev.yml` file that contains the required docker-compose setup. You need to pass the `-f dev.yml` flag you run docker-compose commands to ensure it uses this file. If you don't want to add this each time, you can export it as a `COMPOSE_FILE` variable:
```sh
export COMPOSE_FILE=dev.yml
```
````
To set up your Docker environment:
1. Create a `.env` file to enable customization of your setup.
```sh
touch .env
```
2. Add the following variables to load images and enable access to Django admin pages:
```text
MEDIA_URL=http://localhost:8000/media/
STATIC_URL=http://localhost:8000/staticfiles/
```
3. Create a network for federation support
```sh
docker network create federation
```
Once you've set everything up, you need to build the containers. Run this command any time there are upstream changes or dependency changes to ensure you're up-to-date.
```sh
docker-compose -f dev.yml build
```
## Set up the database
Funkwhale relies on a postgresql database to store information. To set this up, you need to run the `manage.py migrate` command:
```sh
docker-compose -f dev.yml run --rm api python manage.py migrate
```
This command creates all the required tables. You need to run this whenever there are changes to the API schema. You can run this at any time without causing issues.
## Set up local data
You need to create some local data to mimic a production environment.
1. Create a superuser so you can log in to your local app:
```sh
docker-compose -f dev.yml run --rm api pythong manage.py createsuperuser
```
2. Add some fake data to populate the database. The following command creates 25 artists with random albums, tracks, and metadata.
```sh
artists=25 # Adds 25 fake artists
command="from funkwhale_api.music import fake_data; fake_data.create_data($artists)"
echo $command | docker-compose -f dev.yml run --rm -T api python manage.py shell -i python
```
## Manage services
Once you have set up your containers, bring them up to start working on them.
1. Compile the translations:
```sh
docker-compose -f dev.yml run --rm front yarn run i18n-compile
```
2. Launch all services:
```sh
docker-compose -f dev.yml up front api nginx celeryworker
```
This gives you access to the following:
- The Funkwhale webapp on `http://localhost:8000`
- The Funkwhale API on `http://localhost:8000/api/v1`
- The Django admin interface on `http://localhost:8000/api/admin`
Once you're done with the containers, you can stop them all:
```sh
docker-compose -f dev.yml stop
```
If you want to destroy your containers, run the following:
```sh
docker-compose -f dev.yml down -v
```
## Set up federation support
Working on federation features requires some additional setup. You need to do the following:
1. Update your DNS resolver to resolve all your .dev hostnames locally
2. Set up a reverse proxy (such as traefik) to catch .dev requests with a TLS certificate
3. Set up two or more local instances
To resolve hostnames locally, run the following:
::::{tab-set}
:::{tab-item} dnsmasq
```sh
echo "address=/test/172.17.0.1" | sudo tee /etc/dnsmasq.d/test.conf
sudo systemctl restart dnsmasq
```
:::
:::{tab-item} NetworkManager
```sh
echo "address=/test/172.17.0.1" | sudo tee /etc/NetworkManager/dnsmasq.d/test.conf
sudo systemctl restart NetworkManager
```
:::
::::
To add a wildcard certificate, copy the test certificate from the `docker/ssl` folder. This certificate is a wildcard for `*.funkwhale.test`
```sh
sudo cp docker/ssl/test.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
```
To run a reverse proxy for your app:
1. Add the following configuration to your `.env` file:
```text
# Remove any port binding so you can specify this per-instance
VUE_PORT_BINDING=
# Disable certificate validation
EXTERNAL_REQUESTS_VERIFY_SSL=false
# Ensure all links use https
FUNKWHALE_PROTOCOL=https
# Disable host ports binding for the nginx container so that traefik handles everything
NGINX_PORTS_MAPPING=80
```
2. Launch traefik using the bundled configuration:
```sh
docker-compose -f docker/traefik.yml up -d
```
3. Set up as many different projects as you need. Make sure the `COMPOSE_PROJECT_NAME` and `VUE_PORT` variables are unique per instance
```sh
export COMPOSE_PROJECT_NAME=node2
export VUE_PORT=1234 # this has to be unique for each instance
docker-compose -f dev.yml run --rm api python manage.py migrate
docker-compose -f dev.yml run --rm api python manage.py createsuperuser
docker-compose -f dev.yml up nginx api front nginx api celeryworker
```
You can access your project at `https://{COMPOSE_PROJECT_NAME}.funkwhale.test`.

73
docs/developer_documentation/setup/gitpod.md
View file

@ -1,6 +1,73 @@
# Develop using Gitpod
```{include} ../../../CONTRIBUTING.md
:start-after: "### Gitpod"
:end-before: "### Docker"
```{note}
You need a GitHub or GitLab.com account to log in to Gitpod.
```
Funkwhale has a Gitpod instance that gives you all the tools you need to work on Funkwhale's code. You can work on the code in-browser using a hosted VS Code install or open VS Code on your desktop over SSH.
You can open Gitpod directly by clicking the link below. This checks out the `develop` branch for you to work on directly.
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://dev.funkwhale.audio/funkwhale/funkwhale)
If you want to work on a particular branch, commit, or merge request, you can do this straight from the GitLab interface. Select the arrow icon on the {guilabel}`Web IDE` button and select {guilabel}`Gitpod` to open Gitpod with the currently selected branch checked out.
![Select Gitpod as the default web IDE](/_static/images/select-gitpod-in-gitlab.png)
When you start Gitpod, it creates the following using the selected branch:
- A Funkwhale API instance
- A Funkwhale frontend instance
You can access the web app at `http://localhost:8000`. Log in with the following credentials:
- Username – `gitpod`
- Password – `gitpod`
## Work on the frontend
By default, Gitpod spins up an entire Funkwhale stack. If you want to work only on the frontend:
1. Select `File` > `Open Folder`
2. Select `/workspace/funkwhale/front`
Gitpod starts a new Vite server on port 4000. This creates a frontend that isn't connected to any instance.
## GitLab Workflow extension
Gitpod offers a GitLab workflow extension to help manage GitLab issues, merge requests, and pipelines. If you want to use it:
1. Navigate to the personal access token section of your [GitLab profile settings](https://dev.funkwhale.audio/-/profile/personal_access_tokens)
2. Create a personal access token with `api` and `read_user` scopes
3. Paste your token into your [Gitpod variables](https://gitpod.io/variables)
Use the following settings to automatically sign in to the extension with Gitpod. The `funkwhale/*` scope ensures you can use the settings for all Funkwhale-hosted projects.
```{list-table} Environment variables
:header-rows: 1
* - Name
- Value
- Scope
* - `GITLAB_WORKFLOW_INSTANCE_URL`
- `https://dev.funkwhale.audio`
- `funkwhale/*`
* - `GITLAB_WORKFLOW_TOKEN`
- Your token
- `funkwhale/*`
```
## Configure custom instance URL
You can configure Gitpod to use your Funkwhale pod as the default server. This means you can test frontend changes on your pod without selecting it each time. To do this, add the following to your [Gitpod variables](https://gitpod.io/variables):
```{list-table} Environment variables
:header-rows: 1
* - Name
- Value
- Scope
* - `VUE_APP_INSTANCE_URL`
- `https://funkwhale.example.com`
- `funkwhale/funkwhale`
```

52
docs/developer_documentation/setup/vite.md
View file

@ -1,8 +1,48 @@
# Develop using Vite
```{include} ../../../CONTRIBUTING.md
---
start-after: "### Vite"
end-before: "## Contribute to the API"
---
```
If you want to make changes to the frontend, you can use Vite to run a development server. This allows you to run a Funkwhale web app and see changes in real time
1. Clone the repository:
::::{tab-set}
:::{tab-item} SSH
```sh
git clone git@dev.funkwhale.audio/funkwhale/funkwhale.git
cd funkwhale/front
```
:::
:::{tab-item} HTTPS
```sh
git clone https://dev.funkwhale.audio/funkwhale/funkwhale.git
cd funkwhale/front
```
:::
::::
2. Install [Node.js](https://nodejs.org/en/download/package-manager/) and [Yarn](https://classic.yarnpkg.com/lang/en/docs/install/)
3. Install all dependencies:
```sh
yarn install
```
4. Compile the translations:
```sh
yarn i18n-compile
```
5. Launch the devlopment server:
```sh
yarn dev
```
You can access the Funkwhale web app at `http://localhost:8000/front`. Connect this app to your pod by selecting {guilabel}`Switch instance` in the sidebar.