Skip to content

docker.md

Latest commit

 

History

History
209 lines (159 loc) · 6.83 KB

docker.md

File metadata and controls

209 lines (159 loc) · 6.83 KB
Raw

🐳 Docker Deployment

The recommended way to run DVinyl is using Docker. You have two options depending on your needs.

Option 1: Using Pre-built Image (Recommended)

Best for: Most users who just want to run the app. No need to clone the full repository or install Node.js.

1. Setup

Create a new folder and a docker-compose.yml file with this content:

services:
  dvinyl-app:
    image: ghcr.io/kyonew/dvinyl:latest
    container_name: dvinyl_app
    restart: unless-stopped
    ports:
      - "3099:3099"
    volumes:
      - ./public/uploads:/app/public/uploads
    env_file:
      - .env
    depends_on:
      - mongodb

  mongodb:
    image: mongo:latest
    container_name: dvinyl_db
    restart: unless-stopped
    volumes:
      - ./mongo_data:/data/db

volumes:
  mongo_data:

If you are struggling with the deploy, you can try this config (thank you @mistic100) :

services:
  dvinyl-app:
    image: ghcr.io/kyonew/dvinyl:latest
    pull_policy: missing
    container_name: dvinyl_app
    restart: unless-stopped
    depends_on:
      - mongodb
    environment:
      - MONGODB_URL=mongodb://mongodb:27017/dvinyl
      - VINYL_PORT=80
      - BASE_URL=
      - PROD=false
      - PASSJWT=<openssl rand -hex 32>
      - SESSION_SECRET=<a different openssl rand -hex 32>
      - DISCOGS_TOKEN=<something>
    ports:
      - '<external_port>:80'
    volumes:
      - /mnt/<uploads_dataset>:/app/public/uploads

  mongodb:
    image: mongo:latest
    pull_policy: missing
    container_name: dvinyl_db
    restart: unless-stopped
    volumes:
      - /mnt/<mongo_dataset>:/data/db

Older / low-power hardware (Raspberry Pi, older NAS/CPUs). MongoDB 5.0+ requires a CPU with AVX support. If mongodb keeps restarting on such hardware, pin an older major instead:

mongodb:
  image: mongo:4.4.18

This only works on a fresh database. You cannot point an older MongoDB at data files that a newer version already wrote (that's a downgrade, and it's refused). Thank you @oliverjunker for the tip!

2. Prepare Environment

If you don't use environment in your conf file, ensure you have a .env file in the root directory.
For both case, you can use the provided .env.example as a starting point.

Get your API keys here.

3. Launch

docker compose up -d

Then open http://localhost:3099 and follow the setup screen to create your admin account.

Tip

If you have make installed, make docker-up runs this for you. Run make help to see every available command.

Tip

Up and running? The Wiki walks you through actually using DVinyl: adding and importing items, customizing the dashboard, sharing collections and backing up your data.

Option 2: Build from Source

Best for: Developers or those who want to customize the code.

  1. Clone the repo: git clone https://github.com/Kyonew/DVinyl.git
  2. Make your .env file using .env.example and api keys page.
  3. Build and start:
docker compose up --build -d

🔄 Updating

Important

Back up first. Before any update, export a whole-instance backup from the app, open the Instance admin page (/admin/instance) and use Backup → Export and, if you want a belt-and-braces copy, snapshot your ./mongo_data folder while the containers are stopped. Updates are designed to be safe and automatic, but a backup is your one-command way back if anything surprises you.

Warning

Upgrading to 3.1.5 or later: the app now refuses to start when PASSJWT or SESSION_SECRET is still set to one of the placeholder values that earlier examples and templates shipped (SomeComplexPassword, AnotherComplexSecret, ChangeThisToAComplexPassword, ChangeThisToAComplexSecret). They are published, so an instance running one is signing its sessions with a secret anyone can read. If the container restarts in a loop after the update, read its logs: the message names the variable to fix. Replace both with openssl rand -hex 32 values. Everyone is logged out once afterwards, which is expected.

Updating (Pre-built Image)

If you are using the GHCR image (Option 1):

docker compose pull
docker compose up -d
# with make:
make docker-update

Updating (Manual Build)

If you cloned the repository (Option 2):

git pull
docker compose up --build -d

Rolling back

If an update misbehaves, roll the app image back to the previous tag (pin a specific version instead of latest, e.g. image: ghcr.io/kyonew/dvinyl:2.6.0) and restore the instance backup you exported above. Because the app image and your data are separate, downgrading the app is safe; just don't downgrade the MongoDB major below the version that last wrote your data.

💾 Persistence

By default, the database data is stored in a Docker volume named mongo-data. This ensures your collection is not lost when you stop or update the containers.

Images uploaded from an item form are stored under public/uploads/items (the Compose files mount ./public/uploads persistently). Whole-instance and per-collection ZIP backups include every referenced local item image. The historical JSON import format remains supported, but JSON alone cannot transport those files to another installation. When a ZIP export encounters an older JPEG stored inline in MongoDB as a data URL, it moves that image into the archive's images/ directory; restoring the ZIP therefore migrates it to the file-based storage automatically.

🧩 No-code plugins and Docker

Collection types you build with the in-app plugin editor (/create-plugin) are stored in the database. Their plugins/<id>/ folder on disk is only a regenerable cache: DVinyl re-creates it from the database at startup.

In practice, that means:

  • Nothing extra to mount. As long as your database volume is persisted (./mongo_data, which it is in every example here), your no-code plugins survive docker compose pull, up --build and down. DVinyl rebuilds their folders on startup.
  • They travel with an instance backup. An instance export includes your no-code plugin definitions along with everything else, and restoring brings them back.

🗑️ Full reset & Data loss

If you have made significant changes and need to rebuild the application from a clean slate, follow the steps below.

Important

This procedure will permanently delete all local data. If you have data you wish to keep, export your database before proceeding.

# Stop containers and remove volumes (-v)
sudo docker compose down -v

# Delete local database files
sudo rm -rf ./mongo_data

# Rebuild and restart the services
sudo docker compose up -d

← Back to README · Installation guide · Get your API keys →