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

docs: rearrange paths, update links and redirects

Browse source 
Part-of: <https://dev.funkwhale.audio/funkwhale/funkwhale/-/merge_requests/2353>
This commit is contained in:
Ciarán Ainsworth 2023-02-01 13:41:44 +01:00
commit 65316d43c1
169 changed files with 254 additions and 255 deletions
Download patch file Download diff file Expand all files Collapse all files

202
docs/developer/setup/docker.md Normal file
View file

@ -0,0 +1,202 @@
# Develop using Docker
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
sudo 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
sudo 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 `funkwhale-manage migrate` command:
```sh
sudo docker compose -f dev.yml run --rm api funkwhale-manage 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
sudo docker compose -f dev.yml run --rm api funkwhale-manage 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 | sudo docker compose -f dev.yml run --rm -T api funkwhale-manage 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
sudo docker compose -f dev.yml run --rm front yarn run i18n-compile
```
2. Launch all services:
```sh
sudo 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
sudo docker compose -f dev.yml stop
```
If you want to destroy your containers, run the following:
```sh
sudo 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
sudo 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
sudo docker compose -f dev.yml run --rm api funkwhale-manage migrate
sudo docker compose -f dev.yml run --rm api funkwhale-manage createsuperuser
sudo docker compose -f dev.yml up nginx api front nginx api celeryworker
```
You can access your project at `https://{COMPOSE_PROJECT_NAME}.funkwhale.test`.

BIN
docs/developer/setup/gitpod-select-gitpod-in-gitlab.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 87 KiB

73
docs/developer/setup/gitpod.md Normal file
View file

@ -0,0 +1,73 @@
# Develop using Gitpod
```{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](./gitpod-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`
```

15
docs/developer/setup/index.md Normal file
View file

@ -0,0 +1,15 @@
# Set up your development environment
Follow the instructions in these guides to set up your development environment.
```{toctree}
---
caption: Choose your setup
maxdepth: 1
---
gitpod
docker
vite
```

48
docs/developer/setup/vite.md Normal file
View file

@ -0,0 +1,48 @@
# Develop using Vite
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 development 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.