starred/planka
1
0
Fork 0
mirror of https://github.com/plankanban/planka.git synced 2026-02-25 03:14:50 +03:00
Code Issues 396 Packages Projects Releases 16 Wiki Activity

Upcoming breaking changes (currently applies to nightly users) #907

New Issue
Open
opened 2026-02-04 21:36:47 +03:00 by OVERLORD · 0 comments
OVERLORD commented 2026-02-04 21:36:47 +03:00
Owner
Copy Link

Originally created by @meltyshev on GitHub (Jan 31, 2026).

We decided to introduce a few breaking changes shortly before releasing the final v2 version.

  1. S3 is now fully private.
    All files (including those that were previously public) - will be re-streamed through PLANKA. This means your S3 bucket no longer needs a public access policy for publicly accessible files.

  2. New access rules for avatars and background images.
    Since these files can contain sensitive information, access to them will now require a valid user access token. This provides an additional layer of protection starting with the new version.

  3. Unified data folder for all uploads (migration required).
    We are moving all uploaded files into a single, unified data directory. This makes backups simpler, avoids creating a new Docker volume for each upload type (which is difficult to scale), and is best done now before the stable release.

Users upgrading directly from v1 will be covered by an updated upgrade guide, so no extra manual steps will be needed. However, if you are already using any nightly v2 and want to migrate, you must follow the migration steps to move to the new structure.

ℹ️ FOR NOW, THIS APPLIES ONLY TO USERS ON NIGHTLY V2. WE WILL UPDATE THIS MIGRATION GUIDE FOR ALL RC V2 USERS RIGHT AFTER THE FINAL RELEASE (NO ACTION REQUIRED YET FOR RC V2 USERS).

⚠️ PLEASE MAKE A PROPER BACKUP BEFORE PROCEEDING.

For Docker-Based Installations

1. Create a Backup

Navigate to the directory containing your docker-compose.yml file.

Database Backup

The instance should be running while performing the backup.

docker compose exec postgres pg_dump -U postgres planka > planka_backup_$(date +%Y%m%d).sql

Volume Backups

Important: Replace the volume names (planka_favicons, planka_user-avatars, planka_background-images, planka_attachments) below with the actual volume names used in your setup.

After running the commands, verify the created .tar.gz files contain the expected data.

docker run --rm -v $(pwd):/backup -v planka_favicons:/data alpine tar -czvf /backup/favicons.tar.gz -C /data .
docker run --rm -v $(pwd):/backup -v planka_user-avatars:/data alpine tar -czvf /backup/user-avatars.tar.gz -C /data .
docker run --rm -v $(pwd):/backup -v planka_background-images:/data alpine tar -czvf /backup/background-images.tar.gz -C /data .
docker run --rm -v $(pwd):/backup -v planka_attachments:/data alpine tar -czvf /backup/attachments.tar.gz -C /data .

2. Stop and Remove Containers

docker compose down

3. Add New Volume

Edit your docker-compose.yml file and update the volumes sections:

services:
  planka:
    ...
    volumes:
+     - data:/app/data
      - favicons:/app/public/favicons
      - user-avatars:/app/public/user-avatars
      - background-images:/app/public/background-images
      - attachments:/app/private/attachments
    ...

volumes:
+ data:
  favicons:
  user-avatars:
  background-images:
  attachments:
  db-data:

4. Pull the Docker Image

docker compose pull

5. Upgrade to New Data Structure

Copy data files to the new unified volume:

docker compose run --rm planka sh -c 'mkdir -p /app/data/protected /app/data/private && for folder in favicons user-avatars background-images; do cp -av /app/public/$folder /app/data/protected; done && cp -av /app/private/attachments /app/data/private'

6. Run the Upgrade Script

docker compose run --rm planka npm run db:upgrade

7. Remove the Old Volume References

Update your docker-compose.yml to remove the old volumes:

services:
  planka:
    ...
    volumes:
      - data:/app/data
-     - favicons:/app/public/favicons
-     - user-avatars:/app/public/user-avatars
-     - background-images:/app/public/background-images
-     - attachments:/app/private/attachments
    ...

volumes:
  data:
- favicons
- user-avatars:
- background-images:
- attachments:
  db-data:

8. Start PLANKA and Verify

Start PLANKA:

docker compose up -d

Verify:

  • Application starts successfully
  • All uploaded images and files appear correctly

9. Clean Up

Once confirmed everything works, remove the old volumes:

docker volume rm planka_favicons planka_user-avatars planka_background-images planka_attachments

Troubleshooting

If you encounter issues:

  • Check logs with docker compose logs -f planka
  • Ensure every command completed successfully
  • If necessary, restore from your backup and try again

For Manual Installations

1. Stop the Running Service

Navigate to the /var/www/planka directory.

If using systemd

sudo systemctl stop planka

If using PM2

pm2 stop planka

If running directly

Press Ctrl+C in the terminal where PLANKA is running.

2. Create a Backup

Database Backup

sudo -u postgres pg_dump planka > planka_backup_$(date +%Y%m%d).sql

Rename the PLANKA Directory

cd ..
sudo mv /var/www/planka /var/www/planka-backup

3. Create the New Directory and Set Ownership

sudo mkdir -p /var/www/planka/
sudo chown -R planka:planka /var/www/planka/
cd /var/www/planka

4. Switch to the planka User

sudo -i -u planka

5. Download and Extract the Prebuilt Version of PLANKA

curl -fsSL -O https://github.com/plankanban/planka/releases/latest/download/planka-prebuild.zip
unzip -o planka-prebuild.zip -d /var/www/
rm planka-prebuild.zip

6. Copy Required Files From the Previous Version

mkdir -p /var/www/planka/data/protected /var/www/planka/data/private
cp -av /var/www/planka-backup/.env /var/www/planka/
cp -av /var/www/planka-backup/public/favicons /var/www/planka/data/protected
cp -av /var/www/planka-backup/public/user-avatars /var/www/planka/data/protected
cp -av /var/www/planka-backup/public/background-images /var/www/planka/data/protected
cp -av /var/www/planka-backup/private/attachments /var/www/planka/data/private

7. Install Dependencies

cd /var/www/planka
npm install

8. Run the Upgrade Script

npm run db:upgrade

9. Start PLANKA

If using systemd

Exit the planka user session and start the service:

exit
sudo systemctl start planka

If using PM2

Exit the planka user session and start the service:

exit
pm2 start planka

If running directly

npm start --prod

10. Verify the Installation

  • Application starts successfully
  • All uploaded images and files appear correctly

Troubleshooting

Common Checks

  1. Check logs:

    # If using systemd
sudo journalctl -u planka -f

# If using PM2
pm2 logs planka

# If running in foreground, logs are shown in the terminal

  2. Ensure every command completed successfully

  3. Check file ownership and permissions

  4. If necessary, restore from your backup and try again

Fixing Permissions

If you encounter permission issues:

sudo chown -R planka:planka /var/www/planka
Originally created by @meltyshev on GitHub (Jan 31, 2026). We decided to introduce a few breaking changes shortly before releasing the final v2 version. 1. **S3 is now fully private.** All files (including those that were previously public) - will be re-streamed through PLANKA. This means your S3 bucket no longer needs a public access policy for publicly accessible files. 2. **New access rules for avatars and background images.** Since these files can contain sensitive information, access to them will now require a valid user access token. This provides an additional layer of protection starting with the new version. 3. **Unified data folder for all uploads (migration required).** We are moving all uploaded files into a single, unified data directory. This makes backups simpler, avoids creating a new Docker volume for each upload type (which is difficult to scale), and is best done now before the stable release. Users upgrading directly from v1 will be covered by an updated upgrade guide, so no extra manual steps will be needed. However, if you are already using any `nightly` v2 and want to migrate, you must follow the migration steps to move to the new structure. **ℹ️ FOR NOW, THIS APPLIES ONLY TO USERS ON `NIGHTLY` V2. WE WILL UPDATE THIS MIGRATION GUIDE FOR ALL `RC` V2 USERS RIGHT AFTER THE FINAL RELEASE (NO ACTION REQUIRED YET FOR `RC` V2 USERS).** **⚠️ PLEASE MAKE A PROPER BACKUP BEFORE PROCEEDING.** # For Docker-Based Installations ## 1. Create a Backup Navigate to the directory containing your `docker-compose.yml` file. ### Database Backup The instance should be running while performing the backup. ```bash docker compose exec postgres pg_dump -U postgres planka > planka_backup_$(date +%Y%m%d).sql ``` ### Volume Backups > **Important:** Replace the volume names (`planka_favicons`, `planka_user-avatars`, `planka_background-images`, `planka_attachments`) below with the actual volume names used in your setup. > > After running the commands, verify the created `.tar.gz` files contain the expected data. ```bash docker run --rm -v $(pwd):/backup -v planka_favicons:/data alpine tar -czvf /backup/favicons.tar.gz -C /data . docker run --rm -v $(pwd):/backup -v planka_user-avatars:/data alpine tar -czvf /backup/user-avatars.tar.gz -C /data . docker run --rm -v $(pwd):/backup -v planka_background-images:/data alpine tar -czvf /backup/background-images.tar.gz -C /data . docker run --rm -v $(pwd):/backup -v planka_attachments:/data alpine tar -czvf /backup/attachments.tar.gz -C /data . ``` ## 2. Stop and Remove Containers ```bash docker compose down ``` ## 3. Add New Volume Edit your `docker-compose.yml` file and update the `volumes` sections: ``` services: planka: ... volumes: + - data:/app/data - favicons:/app/public/favicons - user-avatars:/app/public/user-avatars - background-images:/app/public/background-images - attachments:/app/private/attachments ... volumes: + data: favicons: user-avatars: background-images: attachments: db-data: ``` ## 4. Pull the Docker Image ```bash docker compose pull ``` ## 5. Upgrade to New Data Structure Copy data files to the new unified volume: ```bash docker compose run --rm planka sh -c 'mkdir -p /app/data/protected /app/data/private && for folder in favicons user-avatars background-images; do cp -av /app/public/$folder /app/data/protected; done && cp -av /app/private/attachments /app/data/private' ``` ## 6. Run the Upgrade Script ```bash docker compose run --rm planka npm run db:upgrade ``` ## 7. Remove the Old Volume References Update your `docker-compose.yml` to remove the old volumes: ``` services: planka: ... volumes: - data:/app/data - - favicons:/app/public/favicons - - user-avatars:/app/public/user-avatars - - background-images:/app/public/background-images - - attachments:/app/private/attachments ... volumes: data: - favicons - user-avatars: - background-images: - attachments: db-data: ``` ## 8. Start PLANKA and Verify Start PLANKA: ```bash docker compose up -d ``` ### Verify: - Application starts successfully - All uploaded images and files appear correctly ## 9. Clean Up Once confirmed everything works, remove the old volumes: ```bash docker volume rm planka_favicons planka_user-avatars planka_background-images planka_attachments ``` ## Troubleshooting If you encounter issues: - Check logs with `docker compose logs -f planka` - Ensure every command completed successfully - If necessary, restore from your backup and try again # For Manual Installations ## 1. Stop the Running Service Navigate to the `/var/www/planka` directory. ### If using systemd ```bash sudo systemctl stop planka ``` ### If using PM2 ```bash pm2 stop planka ``` ### If running directly Press Ctrl+C in the terminal where PLANKA is running. ## 2. Create a Backup ### Database Backup ```bash sudo -u postgres pg_dump planka > planka_backup_$(date +%Y%m%d).sql ``` ### Rename the PLANKA Directory ```bash cd .. sudo mv /var/www/planka /var/www/planka-backup ``` ## 3. Create the New Directory and Set Ownership ```bash sudo mkdir -p /var/www/planka/ sudo chown -R planka:planka /var/www/planka/ cd /var/www/planka ``` ## 4. Switch to the `planka` User ```bash sudo -i -u planka ``` ## 5. Download and Extract the Prebuilt Version of PLANKA ```bash curl -fsSL -O https://github.com/plankanban/planka/releases/latest/download/planka-prebuild.zip unzip -o planka-prebuild.zip -d /var/www/ rm planka-prebuild.zip ``` ## 6. Copy Required Files From the Previous Version ```bash mkdir -p /var/www/planka/data/protected /var/www/planka/data/private cp -av /var/www/planka-backup/.env /var/www/planka/ cp -av /var/www/planka-backup/public/favicons /var/www/planka/data/protected cp -av /var/www/planka-backup/public/user-avatars /var/www/planka/data/protected cp -av /var/www/planka-backup/public/background-images /var/www/planka/data/protected cp -av /var/www/planka-backup/private/attachments /var/www/planka/data/private ``` ## 7. Install Dependencies ```bash cd /var/www/planka npm install ``` ## 8. Run the Upgrade Script ```bash npm run db:upgrade ``` ## 9. Start PLANKA ### If using systemd Exit the `planka` user session and start the service: ```bash exit sudo systemctl start planka ``` ### If using PM2 Exit the `planka` user session and start the service: ```bash exit pm2 start planka ``` ### If running directly ```bash npm start --prod ``` ## 10. Verify the Installation - Application starts successfully - All uploaded images and files appear correctly ## Troubleshooting ### Common Checks 1. Check logs: ```bash # If using systemd sudo journalctl -u planka -f # If using PM2 pm2 logs planka # If running in foreground, logs are shown in the terminal ``` 2. Ensure every command completed successfully 3. Check file ownership and permissions 4. If necessary, restore from your backup and try again ### Fixing Permissions If you encounter permission issues: ```bash sudo chown -R planka:planka /var/www/planka ```
OVERLORD added the documentation label 2026-02-04 21:36:47 +03:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
bug
documentation
documentation
duplicate
enhancement
good first issue
help wanted
pull-request
Mirrored from GitHub Pull Request
 question
wontfix
No Label documentation
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
OVERLORD
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/planka#907
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?