Installation Guide¶
There are two ways of installing DiscoDOS:
Released version (get a program that just works, is easy to install and well tested)
Development version (get the latest features, contribute to DiscoDOS by trying out new things and reporting back what you think. There is a separate document about installing the development version.
Install released version¶
Windows¶
Download the latest Windows installer (DiscoDOS_version.exe
) from the release page and run it.
Click Start Menu - DiscoDOS - DiscoDOS
A new command prompt window opens and the DiscoDOS main command disco
runs automatically.
On first launch, disco
will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter Configure Discogs API access, then come back here!
Now that you’ve put the token into the configuration file, DiscoDOS completes setup by creating a local database (the DiscoBASE).
Note: In case you are updating from a previous DiscoDOS version, your data will be kept and your database’s schema might be upgraded automatically
If the connection to Discogs is working, setup asks you to view a little tutorial teaching you how it works - hit enter and follow the steps.
Your starting point for further documentation is the Quickstart Guide. Your next logical step is importing your Discogs collection.
Note: The disco
and discosync
commands are installed globally, you can use the Start Menu entry to run them but they also work in any cmd.exe window
Note: DiscoDOS generates the following files which are kept in C:\Users\your_name\Documents\discodos\
(path may vary depending on your OS-language):
The DiscoDOS configuration file (
config.yaml
)The DiscoBASE (
discobase.db
)A logfile (
debug.log
)
macOS¶
Download the latest macOS package (DiscoDOS_version.dmg
) from the release page
Doubleclick the .dmg file - Drag and drop DiscoDOS.app
to Applications
folder.
Launch DiscoDOS.app
A new Terminal window opens and the DiscoDOS main command disco
runs automatically.
On first launch, disco
will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter Configure Discogs API access, then come back here!
Now that you’ve put the token into the configuration file, DiscoDOS completes setup by creating a local database (the DiscoBASE).
Note: In case you are updating from a previous DiscoDOS version, your data will be kept and your database’s schema might be upgraded automatically
If the connection to Discogs is working, setup asks you to view a little tutorial teaching you how it works - hit enter and follow the steps.
Your starting point for further documentation is the Quickstart Guuide. Your next logical step is importing your Discogs collection.
Note: The disco
and discosync
commands are now installed globally, you can launch DiscoDOS.app to open a Terminal but they also work in any other Terminal window.
Note: DiscoDOS generates the following files which are kept in /Users/your_name/Documents/DiscoDOS/
:
The DiscoDOS configuration file (
config.yaml
)The DiscoBASE (
discobase.db
)A logfile (
debug.log
)
Linux¶
Most Linux distributions come with a compatible Python3 version in there package repositories already. Please refer to the contribution manual on how to install the DiscoDOS Python package.
If you use Debian GNU/Linux or any distribution that is based on it: DiscoDOS v1.0_rc2 is available in Debian unstable. It is also available in the current Ubuntu release as well as in Ubuntu Studio, Linux Mint and other Ubuntu-based distros. Just apt install discodos
and you are good to go. If you’d like to use the latest version of DiscoDOS please be patient or even better: Install DiscoDOS as a Python package. Learn how by following above link to the contribution manual.
Configure Discogs API access¶
To access your Discogs collection you need to generate an API login token and put it into the configuration file.
Login to discogs.com
Click your avatar (top right)
Select Settings
Switch to section Developers
Click Generate new token
Run
disco
- you’ll be prompted to put in the token.
Note: If you are updating from a previous DiscoDOS version, your config.yaml is existing and has a token set up already, thus you won’t be bothered!
Jump back to Windows installation chapter
Jump back to macOS installation chapter
Jump back to Linux installation chapter
Edit configuration file manually¶
Alternatively you can open the configuration file with a texteditor and copy/paste the generated Discogs token into it by hand:
Windows: Edit
MyDocuments/discodos/config.yaml
(use Start Menu entry “DiscoDOS/Edit Configuration File”)macOS: Edit
/Users/your_name/Documents/config.yaml
(secondary click (two fingers) - “Open With” - “TextEdit.app”).Linux: Edit
$HOME/.discodos/config.yaml
The line in config.yaml
should look something like this then:
discogs_token: XDsktuOMNkOPxvNjerzCbvJIFhaWYwmdGPwnaySH
Configure discosync - The DiscoDOS backup & sync tool¶
discosync
works with timestamps (local modification time) of the database file. It will never backup a file that has been already backuped up. Even if the file has been shared to another computer, it will only be overwritten if its contents was changed. This is to reduce the amount of (useless) backup files in your dropbox account or on your webserver.
The format of files always is “database_name_YYYY-MM-DD_HHMMSS.db”
Configure Dropbox Access for discosync¶
To prepare your Dropbox account and DiscoDOS configuration, do the following:
We need to create a new “Dropbbox App” in your account: https://www.dropbox.com/developers/apps/create
Step 1: “Choose an API” - select “Dropbox API”
Step 2: “Choose the type of access you need” - select “App folder”
Step 3: “Name your app” - enter “discodos”
Click “Create app”
Scroll down to section “OAuth 2” - Click the “Generate” button right below “Generated access token”
Double click and copy the token to the clipboard
Put the token into the config.yaml file on all the computers you would like to use this DiscoBASE.
open with TextEdit.app on Mac
open with Notepad on Windows.
The line in config.yaml should then look something like this (watch out for the surrounding quotes):
dropbox_token: 'abcxyzabcxyzabcxyzabcxyzabcxyzabcxyzabcxyz'
Jump back to I’d like to use my DiscoBASE on multiple computers
If you want to delete your Dropbox app again or generate a new token because you lost it, go to the Dropbox app console.
Certainly you can also access the backup files via the Dropbox webinterface - Click the “discodos” app on the home screen - you will find a subfolder “discodos” containing all your backed up DiscoBASE files.
Configure a webserver folder for discosync¶
If you don’t like saving your stuff to Dropbox and happen to have your own personal webspace somewhere, discosync
can use it to save backups. The folder needs to have these features enabled:
Password restriction (HTTP Basic Access Authentication)
Even though it is not mandatory, the following is highly recommended to securly transport your password over the wire:
Webserver running SSL (https://…)
Configuration steps may vary, if you can’t do above configurations in your webhosters “configuration console” try contacting their support.
If you have (root) access to your server and it’s an Apache webserver, configuration of a suitable folder looks like this:
<Directory /var/www/discodos/>
AllowOverride None
DAV On
AuthType "Basic"
AuthName "Restricted Area"
AuthBasicProvider file
AuthUserFile "/etc/apache2/.htaccess_discodos"
Require user my_discosync_user
</Directory>
To create the password file:
htpasswd -c /etc/apache2/.htaccess_discodos my_discosync_user
Test if accessing your backup space is working with your webbrowser: https://www.yourdomain.com/discodos/. Usually a popup asks you for your credentials.
If everything’s fine adjust your DiscoDOS configuration file (config.yaml
)
webdav_user: 'my_discosync_user'
webdav_password: 'secret123'
webdav_url: 'https://www.yourdomain.com/discodos/'
Go to the discosync chapter in the User’s manual