From 34ec7b542f67d9fca18b2a045fa29adefd12d670 Mon Sep 17 00:00:00 2001
From: Eliot Berriot <contact@eliotberriot.com>
Date: Sun, 25 Jun 2017 23:33:19 +0200
Subject: [PATCH] Added documentation about music acquisition

---
 .gitignore                   |  1 +
 deploy/docker-compose.yml    |  4 +++-
 docs/importing-music.rst     | 40 ++++++++++++++++++++++++++++++++++++
 docs/index.rst               |  2 +-
 docs/installation/docker.rst |  5 +++++
 5 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 docs/importing-music.rst

diff --git a/.gitignore b/.gitignore
index 130ed29ad..c1b8300f2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -67,6 +67,7 @@ mailhog
 *.sqlite3
 
 # Api
+demo/music
 api/music
 api/media
 api/staticfiles
diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml
index 9ce6ecd74..1a1b81b39 100644
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -25,7 +25,8 @@ services:
     environment:
       - C_FORCE_ROOT=true
     volumes:
-    - ./api/media:/app/funkwhale_api/media
+      - ./data/music:/music:ro
+      - ./api/media:/app/funkwhale_api/media
 
   celerybeat:
     restart: unless-stopped
@@ -42,6 +43,7 @@ services:
     env_file: .env
     command: ./compose/django/gunicorn.sh
     volumes:
+      - ./data/music:/music:ro
       - ./data/media:/app/funkwhale_api/media
       - ./data/static:/app/staticfiles
     ports:
diff --git a/docs/importing-music.rst b/docs/importing-music.rst
new file mode 100644
index 000000000..15db0756b
--- /dev/null
+++ b/docs/importing-music.rst
@@ -0,0 +1,40 @@
+Importing music
+================
+
+From music directory on the server
+----------------------------------
+
+You can import music files in funkwhale assuming they are located on the server
+and readable by the funkwhale application.
+
+Assuming your music is located at ``/music`` and your music files contains at
+least an ``artist``, ``album`` and ``title`` tag, you can import those tracks as follows:
+
+.. code-block:: bash
+
+    docker-compose --rm run api python manage.py import_files "/music/**/*.ogg" --recursive --noinput
+
+.. note::
+
+    This command is idempotent, meaning you can run it multiple times on the same
+    files and already imported files will simply be skipped.
+
+.. warning::
+
+    At the moment, only ogg files are supported. MP3 support will be implemented soon.
+
+Getting demo tracks
+^^^^^^^^^^^^^^^^^^^
+
+If you do not have any music on your server but still want to test the import
+process, you can call the following methods do download a few albums licenced
+under creative commons (courtesy of Jamendo):
+
+.. code-block:: bash
+
+    curl -L -o download-tracks.sh "https://code.eliotberriot.com/funkwhale/funkwhale/raw/master/demo/download-tracks.sh"
+    curl -L -o music.txt "https://code.eliotberriot.com/funkwhale/funkwhale/raw/master/demo/music.txt"
+    chmod +x download-tracks.sh
+    ./download-tracks.sh music.txt
+
+This will download a bunch of zip archives (one per album) under the ``data/music`` directory and unzip their content.
diff --git a/docs/index.rst b/docs/index.rst
index 22438f209..b4c4119bf 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,7 +13,7 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in
 
    features
    installation/index
-
+   importing-music
 
 
 Indices and tables
diff --git a/docs/installation/docker.rst b/docs/installation/docker.rst
index a0b397d6d..9f7a288f3 100644
--- a/docs/installation/docker.rst
+++ b/docs/installation/docker.rst
@@ -47,3 +47,8 @@ Then launch the whole thing:
     docker-compose up -d
 
 Now, you just need to setup the :ref:`frontend files <frontend-setup>`, and configure your :ref:`reverse-proxy <reverse-proxy-setup>`. Don't worry, it's quite easy.
+
+About music acquisition
+-----------------------
+
+If you want to :doc:`import music located on the server </importing-music>`, you can put it in the ``data/music`` directory and it will become readable by the importer.