Hi all,

I installed the turnkey appliance Mayan EDMS, and it works out of the box. However the docs state that it's running version 2.2, so I tried to upgrade it to 2.7.3 by following the instructions:

https://mayan.readthedocs.io/en/latest/releases/2.7.3.html

I ran the pip upgrade command, and the performupgrade and collect stuff, but it doesn't seem to work.

The about page of the web ui still shows 2.2 as the version number.

Anyone has an idea?

Forum: 
Tags: 
Ken Robinson's picture

Hey there! Your in luck as I am the dev that got Mayan in the Turnkey Library so I am very in touch with this one! I have not tested the upgrade path from the Mayan site to v 2.7 but it should have worked. That said I'll spin one up here and try it out. 

Can you give me some background on what type of install you performed (ISO/Xen/VM Image/Proxmox etc.)

 

Regards,

Ken  
":0)

http://www.github.com/DocCyblade

Ken Robinson's picture

So my inital testing shows that a lot has changed from v2.2 to v2.7 enough to break the upgrade. 

I also noticed that the developer no longer supports an install like we perform when build Turnkey images and uses Docker. I am going to reach out to him to see if he will help with our platform. 

When I have a some more time tonight I'll check to see what version you can upgrade to until it does not work, and post those steps to do the upgrade.

Regards,

Ken  
":0)

http://www.github.com/DocCyblade

Ken Robinson's picture

So it looks like the dev still supports an "advanced install" so I will have to see what is breaking. I am working on it tonight. Will post back when I find somthing more.

Regards,

Ken  
":0)

http://www.github.com/DocCyblade

Ken Robinson's picture

These steps where tested on v14.2 Turnkey Mayan ISO to Mayan v2.7.3

So I tried to do an update and I was able to get it to work by doing the below steps. 

1. Login to console as root

2. Stop all the services for Mayan. Make sure each step completes before going on to the next.

# Stop the web server
service nginx stop

# Stop the mayan uwsgi, worker and beat services
supervisorctl stop all

# Stop the redis queue server
service redis-server stop

 

3. We installed Mayan in a virtual environment so we must activate it to update Mayan

source /usr/share/mayan-edms/bin/activate

 

4. Add missing dependancies

apt-get install graphviz -y

 

5. Update using pip

pip install -U mayan-edms


6. Run migration for database

mayan-edms.py performupgrade


7. Update static media files

mayan-edms.py collectstatic --noinput


8. Exit the virtual enviroment

deactivate

 

9. Remove old lock file

rm /tmp/mayan_locks.tmp

 

10. Logging was added, update log file location and create with with correct user

# Add logging option to local settings file
echo "COMMON_PRODUCTION_ERROR_LOG_PATH = '/var/log/mayan/mayan-error.log'" >> /usr/share/mayan-edms/mayan/settings/local.py

# Create new log file and set permissions
touch /var/log/mayan/mayan-error.log
chown www-data:www-data /var/log/mayan/mayan-error.log

 

11. Restart the services

# Start the redis queue server
service redis-server start

# Start the mayan uwsgi, worker and beat services
supervisorctl start all

# Start the web server
service nginx start

 

Regards,

Ken  
":0)

http://www.github.com/DocCyblade

Jeremy Davis's picture

My only comment is, that wouldn't it be better to chown the whole log directory (/var/log/mayan/)? Then you could use logrotate to make sure the log file doesn't get out of control...

My 2c anyway. Regardless, thanks again Ken! You're a living legend! :)

Thanks a lot Ken! I was using the OVF for testing, but will switch to a new VM based on the ISO.

I will first try your instructions on the OVF ;-)

Thanks again!

Jeremy Davis's picture

Ken's instructions should equally apply to the OVA/OVF build as it would to ISO (or any other build in fact). Obviously there are some differences in each buildtype, but all the different builds start life as the ISO.

Please let us know how you go. If you hit any issues, please post back and we'll do our best to head you in the right direction.

Jeremy Davis's picture

The upgrade process may be somewhat similar, but should be a bit easier (hopefully). FWIW, the v15.0 release was significantly refactored to follow the upstream documentation as closely as possible (to make upgrades easier - hopefully).

Please also note that when the v15.0 appliance was released, I did my best to document upgrade instructions. Having said that, I note that the link to the release notes is broken, you will now find them here. I also note that when I did the update, the method that we used was under "advanced deployment". The link that I gave to those instructions has also changed, and the terminology no longer refers to our install method as "advanced deployment", but instead "basic deployment" as a sub-topic of "direct deployment" (to reiterate, we DID NOT do what is now referred to as "advanced"). The doc page I'm referring to can now be found here.

Personally, what I'd be inclined to do would be to do a full backup of your current system, then do a test update using a backup of your site to ensure that everything works as it should. Worst case scenario, if something goes wrong, you haven't damaged your existing (and I assume working) install.

If you're using TKLBAM, you should be able to simply restore your v15.0 backup to a new v15.0 server and use that as a base to test on. The added bonus of that is that it allows you to also test your backup to ensure that it includes everything required. Personally I'd restore to a local VM (i.e. download the OVA - or the ISO - and install to a local VM such as within VirtualBox), but that's entirely up to you. If you are already using a local VM (or an AWS server) then you could also just take a "snapshot" of your current server so that you can roll back if need be. Although please test your snapshot before you start, to ensure that you can roll back if need be!

Once you've got your test server ready to go (or have taken a snapshot and confirmed that it works) then I'd suggest that you read through the release notes of each version between the current version you are using (v3.1.3) and the latest version (v3.1.9). I.e. start with the notes for v3.1.4. That will give you an understanding of what has changed in Mayan.

From what I can gather, it seems that the instructions that I provided previously (i.e. here) provide many more steps and details to what is now recommended. Some of the constraints will still apply (e.g. using su) but otherwise it seems it should be a bit more straight forward. I also note that the Mayan doc pages also include removal of deprecated requirements.

TBH, I'm not 100% sure whether you would be best to upgrade each version one-by-one, or whether you could get away with just jumping straight to the latest. Assuming that you are following my advice above and are using a test server (or have a confirmed working snapshot) then I'd probably initially try jumping straight to the latest and back track if that fails.

So combining the docs I wrote previously and the current recommendation by Mayan, this is what I'd try first:

REMOVE=/etc/mayan/removals.txt
curl https://gitlab.com/mayan-edms/mayan-edms/raw/master/removals.txt > $REMOVE
supervisorctl stop all
ENV=/etc/mayan/env
BIN=/opt/mayan-edms/bin
su - mayan -c ". $ENV && $BIN/pip uninstall -r $REMOVE"
su - mayan -c ". $ENV && $BIN/pip install mayan-edms==3.1.9"
supervisorctl start all

Hopefully that does the trick. Please post back and let us know how you go. If you have any issues, please provide as much info as possible about what went wrong and I'll do my best to help out...

PS I've opened an issue on our tracker so the required updates don't get forgotten. Hopefully it may assist others that wish to upgrade in the meantime to find their way here.

Nick Boyle's picture

Make sure Docker is properly installed and working before attempting to install Mayan EDMS. For the complete set of installation, configuration, upgrade, and backup instructions visit the Mayan EDMS Docker Hub page.

Jeremy Davis's picture

Thanks for trying to help out nick, but the TurnKey Mayan-EDMS appliance includes Mayan installed as a "direct deployment" so no Docker required. :)

Jeremy Davis's picture

I'll assume that you can upgrade to v3.1.9 ok?!

TBH, it's been a while since I've looked at Mayan-EDMS and I forget whether you need to go through each single version upgrade, or whether you can jump to specific versions. Looking at the Mayan-EDMS upgrade doc page, that suggests that you may be able to upgrade between the "final" versions. I assume that they mean the last release of each major.minor version - e.g. upgrade to v3.1.11; then to v3.2.11; then to v3.3.17; then to the current v3.4.7 - but I'm not 100% sure. I am sure that there are a few important steps that are required along the way and I'm guessing that you haven't done them (hence why things are breaking).

I did try to make the TurnKey appliance as close to the Mayan-EDMS recommendations as possible, whilst still being consistent with how our other appliances are built and our existing "best practice" processes. I did also try to make it as easy for TurnKey users to upgrade the TurnKey appliance as possible, but unfortunately it won't quite match what the Mayan-EDMS docs note and the commands will need to be somewhat tweaked.

Unfortunately, without stepping through the process myself, I can't really give you explicit instructions on what to do. But as hinted above, hopefully you'll find the Mayan-EDMS release notes and upgrade docs useful. I'll give you a few pointers below, and I'm more than happy to help you with your upgrade if/when you hit steps that don't work.

Having said that, we're probably better off starting a new thread to discuss that as this one is already quite long and also quite old. So please sign up for a (free) website user account and start a new thread. It'd probably be also useful for others if you can share your experience.


In the meantime, I'll post some info to get your started here.

So firstly, it's probably worth looking at the v3.1.9 upgrade page to get a bit of a feel of the difference between the upstream (i.e. Mayan-EDMS) docs, and what we do on TurnKey. So to be a bit more explicit; I'll provide a roundup of the Mayan docs. Note that I've consolidated the pip instructions (the first 2 lines below) with the common steps (second 2 lines):

curl https://gitlab.com/mayan-edms/mayan-edms/raw/master/removals.txt | pip uninstall -r /dev/stdin
pip install mayan-edms==3.1.9
mayan-edms.py performupgrade
mayan-edms.py collectstatic --noinput

First up, I'd like to note that we aren't running those last 2 lines (the 'mayan-edms.py' lines). IIRC that was because they were only required when doing an upgrade from Mayan-EDMS v2.x.x to v3.x.x, so I left them out. I'll note how we would run those below, so you'll know how to do it if there are similar lines later.

So now we'll compare the above (top 2 lines of) Mayan docs against the documented TurnKey instructions you've reiterated:

REMOVE=/etc/mayan/removals.txt
curl https://gitlab.com/mayan-edms/mayan-edms/raw/master/removals.txt > $REMOVE
supervisorctl stop all
ENV=/etc/mayan/env
BIN=/opt/mayan-edms/bin
su - mayan -c ". $ENV && $BIN/pip uninstall -r $REMOVE"
su - mayan -c ". $ENV && $BIN/pip install mayan-edms==3.1.9"
supervisorctl start all

Obviously the TurnKey instructions are more lines, let me point out a few things:

  1. Downloading the 'removals.txt' text file is split up into a few separate lines; rather than a single line. We do it that way as we download it initially as the root user, then apply it as the mayan user. That's not so easy to do in one line (and would be hard to read).
  2. Unlike the Mayan docs, we explicitly stop and start the Mayan services (via supervisorctl command). My testing showed that that reduced the risk of race conditions and issues. I suggest that you also stop and start the same way when you do each upgrade.
  3. We provide and use a "convenience env script" (note the use of ENV and the file; /etc/mayan/env). When Mayan instructions note changes to the Mayan environment, you'll also want to update that file with the appropriate values.
  4. When using the 'pip' command (or 'mayan-edms.py' too I think), you'll want to run them in the form of the 'su ...' commands that I noted 9so they run as the mayan user). You'll also want to prefix them (at least pip anyway) with $BIN (e.g. $BIN/pip as I did in that script).
  5. I hope that's enough to get you started. If you need more explanation, please let me know. Although as I say, probably best to start a new thread (feel free to cross post a link to the new thread here, I'll see it regardless).

Morkg's picture

Hi Jeremy

  thank you for the help, created a new thread as you requested to follow up with more issues please get to it from here

 

<a>https://www.turnkeylinux.org/forum/support/fri-20200515-1115/upgrade-may...

 

thank you

Add new comment