# Setup ## Prerequisites DiscoDOS requires Python version 3.9 or higher, getting it differs according to your OS: * Most Linux distributions have Python available within their package repositories. * On Windows [download from here](https://www.python.org/downloads). * On MacOS I suggest [getting Python via homebrew](https://brew.sh/) (or install it manually using the Windows link above). 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! ```sh 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: ```sh 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. ::: * 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](INSTALLATION.md#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). * Optionally and if you plan on using DiscoDOS for selling records, set `discogs_sold_folder_id` in the configuration file. Read [Configuration via a text editor](#configuration-via-a-text-editor) and [There are several ways a record will be auto-marked as sold](MANUAL.md#there-are-several-ways-a-record-will-be-auto-marked-as-sold) * Read the [Quickstart Guide](QUICKSTART.md#importing-your-discogs-collection-and-marketplace-inventory) on how to **import** your Discogs collection and Marketplace inventory. ### 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: ```sh 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](QUICKSTART.md#id-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](https://www.dropbox.com/developers/apps?_tk=pilot_lp&_ad=topbar4&_camp=myapps). 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: - [WebDAV](https://en.wikipedia.org/wiki/WebDAV) - Password restriction ([HTTP Basic Access Authentication](https://en.wikipedia.org/wiki/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: ``` AllowOverride None DAV On AuthType "Basic" AuthName "Restricted Area" AuthBasicProvider file AuthUserFile "/etc/apache2/.htaccess_discodos" Require user my_discosync_user ``` 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](MANUAL.md#discosync---the-discodos-backup--sync-tool)