Deck Deployment and Usage Guide

Deck is a kanban-style project and personal management tool for Nextcloud, similar to Trello. This guide covers installation, configuration, building, and deployment.

1. Prerequisites

Before installing Deck, ensure you have the following:

A running Nextcloud server (version compatible with the Deck app).
Administrator access to your Nextcloud instance to install apps.
For development and building:
- Node.js (for JavaScript dependencies and building).
- Composer (for PHP dependencies).
- Git (for cloning the repository).

2. Installation

Deck can be installed in two ways: via the Nextcloud App Store or manually from a release.

Via Nextcloud App Store (Recommended for End Users)

Log in to your Nextcloud instance as an administrator.
Navigate to Apps → Organization.
Find Deck and click Enable.

Manual Installation from Release

Download the latest release from the Deck releases page.
Extract the archive into your Nextcloud apps/ directory.
Rename the extracted folder to deck.
Enable the app via the Nextcloud apps management page or by running:
```
occ app:enable deck
```
from your Nextcloud root directory.

For Developers: Clone and Install from Source

git clone https://github.com/nextcloud/deck.git
cd deck
composer install --no-dev
npm ci
npm run build

Then, copy or symlink the deck directory to your Nextcloud apps/ folder and enable the app via occ or the web interface.

3. Configuration

Deck integrates directly with Nextcloud and uses its configuration. No separate environment variables or API keys are required for basic functionality.

Key Integration Points

Circles App: For advanced sharing and team management, install and enable the Circles app.
File Attachments: Deck uses Nextcloud's file storage; ensure sufficient storage is available.
Database: Deck uses the Nextcloud database. Ensure your Nextcloud database performance is optimized, especially for larger deployments (see Performance Limitations below).

Performance Limitations

Note that Deck may experience performance issues with intensive usage. For example, a user with access to 13 boards, each with ~100 cards and ~5 attachments per card, can generate ~6500 database queries during file-related operations, impacting page load times. Optimize your Nextcloud server and database for better performance.

4. Build & Run

Development Build

To build Deck for development:

npm run dev

To watch for changes and rebuild automatically:

npm run watch

Production Build

npm run build

Hot Module Replacement (HMR) for Faster Frontend Development

Install and enable the hmr_enabler app in your Nextcloud instance.
Run the development server:
```
npm run serve
```
Access your Nextcloud instance via its normal URL (not the HMR server URL). Changes will reflect without full page reloads.

Development Environments

You can develop Deck using:

GitHub Codespaces / VS Code devcontainer: The repository includes a devcontainer configuration that sets up Nextcloud and Deck automatically.

Docker (simple app development):

docker run --rm -p 8080:80 -v $(pwd):/var/www/html/apps-extra/deck ghcr.io/juliushaertl/nextcloud-dev-php81:latest

This mounts your local Deck directory into a Nextcloud development container.

Full Nextcloud development environment: Set up a Nextcloud development environment and clone Deck into the apps/ directory.

5. Deployment

Deck is deployed as part of Nextcloud. Choose a deployment method suitable for your Nextcloud instance:

Recommended Platforms

Self-hosted Nextcloud: Deploy on your own server using:
- Docker: Use the official Nextcloud Docker image and install Deck via the App Store or manual installation.
- Traditional LAMP/LEMP stack: Install Nextcloud on Linux with Apache/Nginx, PHP, and a database (MySQL/MariaDB, PostgreSQL). Then install Deck as described in the Installation section.
Nextcloud Hosting Providers: Many Nextcloud-focused hosting providers support one-click app installation; enable Deck via their control panel.
Cloud/VPS: Deploy Nextcloud on cloud platforms like AWS, DigitalOcean, or Hetzner, then install Deck.

Post-Deployment

Verify Deck is enabled in Apps → Organization.
Assign users/groups to boards via the Deck interface.
Consider integrating with mobile apps:
- Android (F-Droid / Google Play)
- iOS (Apple App Store)

6. Troubleshooting

Common Issues and Solutions

Deck App Not Appearing

Ensure the app is correctly placed in the apps/ directory and named deck.
Check Nextcloud logs for errors: tail -f /var/www/html/data/nextcloud.log.
Enable debug mode in Nextcloud's config.php to get detailed error messages.

Performance Issues / Slow Loading

Review the Performance Limitations section. Optimize your database:
- Add indexes for Deck tables.
- Increase database memory limits.
- Consider scaling your Nextcloud instance hardware.
Reduce the number of cards/attachments per board if possible.

Missing Features (Circles, File Attachments)

Ensure required Nextcloud apps (like Circles) are installed and enabled.
Check file permissions in Nextcloud's storage.

Build Failures

Ensure Node.js and Composer are up to date.

Clear npm and Composer caches:

npm cache clean --force
composer clear-cache

Verify all dependencies are installed: npm ci and composer install --no-dev.

HMR Not Working

Confirm the hmr_enabler app is installed and enabled.
Ensure you are accessing the normal Nextcloud URL, not the HMR server URL.

Database Errors After Updates

Run Nextcloud's upgrade routine:
```
occ upgrade
```
Check for Deck-specific database migrations.

Mobile App Connection Issues

Verify your Nextcloud instance is accessible via HTTPS (required for most mobile apps).
Ensure the correct server URL and credentials are used in the mobile app.

For further assistance, refer to the Deck API documentation or join the IRC channel #nextcloud-deck on Freenode.

How to Deploy & Use deck