Setup#

Prerequisites#

DiscoDOS requires Python version 3.9 or higher, getting it differs according to your OS:

Make sure python can be executed from everywhere (adjust your path environment variable accordingly, usually $PATH or %PATH%).

During the Python setup on Windows choose Customize installation and select the following options:

  • pip

  • py launcher

  • Associate files with Python (requires the py launcher)

  • Add Python to environment variables

Windows#

Please use the regular command prompt window (cmd.exe) and not the “git bash”, otherwise the statements using the %HOMEPATH% environment variable won’t work! Also note that Windows paths can be written with slashes instead of the usual backslashes these days (putting them inside of quotes is mandatory though!) - in the very unlikely case your Windows version doesn’t support this, please just change the paths to use backslashes.

Create and activate a virtual Python environment!

python -m venv "%HOMEPATH%/python-envs/discodos"
"%HOMEPATH%/python-envs/discodos/Scripts/activate.bat"

Double check if your environment is active and you are using the pip binary installed inside your %HOMEPATH%/python-envs/discodos directory.

pip --version

Install DiscoDOS and its dependencies into your environment:

pip install discodos

Launch DiscoDOS’ main command and follow the steps shown:

dsc

Tip

Make sure you always first activate your virtual environment when coming back to developing or using DiscoDOS.

"%HOMEPATH%/python-envs/discodos/Scripts/activate.bat"

macOS or Linux#

Install to user environment with pipx#

This chapter describes how to install the DiscoDOS package into your user’s Python environment which is better suitable for just using it, rather than contributing/developing.

Install Python 3. On Debian based distros (Ubuntu, Linux Mint, …), do something like this:

apt install python3 pipx

on RedHat based (Fedora, CentOS, …):

yum install python3 pipx

Install DiscoDOS into your user’s Python environment:

pipx install discodos

Verify installation#

Some command wrappers should have been installed. Verify if they exist:

which dsc
which discosync

If which didn’t find those commands, make sure your $PATH environment variable contains the path the wrappers where installed to. Usually this is ~/.local/bin/

Note: On Debian-based systems there might be a file /usr/bin/dsc on your system already provided by package mono-devel, thus depending on the order of paths in $PATH, /usr/bin/dsc might be found before the DiscoDOS wrapper. Change $PATH to first search in ~/.local/bin (export it in .zshrc, .bashrc or whatever shell you are using)

Launch DiscoDOS’ main command:

dsc

Initial configuration and additional notes#

Attention

On first launch, dsc will create a configuration file for you.

Files generated by setup#

DiscoDOS generates the following files which are kept in ~/.discodos/:

  • The DiscoDOS configuration file (config.yaml)

  • The DiscoBASE (discobase.db)

  • A log file (debug.log)

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 dsc - you’ll be prompted to put in the token.

Attention

When upgrading from a previous DiscoDOS version no token prompt occurs (it’s set already in the config file) but you might see automatic DiscoBASE schema upgrades happening.

Configuration via a text editor#

Not only the token but many other settings are found in config.yaml:

  • Windows: Use eg. notepad to open the file in your home folder (usually \Users\yourname\.discodos - be aware of the leading dot in the directory’s name!)

  • macOS: The .discodos directory in your home folder is hidden, Use Finder’s “Go to folder…” command in the “Go” menu. Put in /Users/yourname/.discodos.

  • Linux: Edit $HOME/.discodos/config.yaml with any text editor.

For example the Discogs API token’s line in config.yaml looks something like this:

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'

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:

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