suma documentation

[Schwen]

We have suma setup for our library, however there was almost no documentation left behind by the old admin. Our current install needs updating as websql is becoming an issue, and the server is still Redhat 6.

So, I am looking for documentation that might address a new setup, and also docs on what I need to update on our current install.

Thanks!

[aurelian grinnellian]

I would also welcome instructions on the update process as I am new the application and we also need to upgrade the client due to websql.  The instructions I did find are basic, and I don't want to miss anything.

Best,

Erika

[Kevin Beswick]

Hi all,

Here are the installation instructions for Suma: https://suma-project.github.io/Suma/installation/

In terms of updating specifically for the new client that replaces the older WebSQL one, if you cloned the project from GitHub, you'd just need to run a "git pull" on your cloned directory and that should be all. If you downloaded the Suma code, you would just need to download the new version of the code, unzip and then copy into the same place as your old code. Be sure to make a backup copy of your old code (and especially your configuration files) just in case. The new client is a drop-in replacement, so there is no additional configuration or changes you should need to make to an existing installation that you are upgrading, and it should be available at the same URL as the old client. 

I'm happy to answer any more questions you have!

Thanks,

Kevin

--
You received this message because you are subscribed to the Google Groups "Suma: mobile library assessment toolkit" group.
To unsubscribe from this group and stop receiving emails from it, send an email to suma-mobile-library-asses...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/suma-mobile-library-assessment-toolkit/68b0d8d2-b23e-4a4c-9610-687c1edaff94n%40googlegroups.com.

--

Kevin Beswick

Associate Head, Digital Library Initiatives

NC State University Libraries

919-513-2612 | kdbe...@ncsu.edu

[Schwen]

See, that's the question. How is a git pull done? Let's assume I know zero about suma, which is basically the case. I tried to download the latest package, and replace the directories(similar to the client install instructions), and that just caused the program to stop working. I have no idea of any of the install. It was done years back. I don't know if I have a server or client install, nothing. SO, that does not help matters.

[Ian Dean]

Before you do the upgrade you should try to see how it was initially installed.

A "git pull" uses the git commands from the command line and essentially updates your version of the files to what the latest version is in the master branch or whatever branch you are using. I don't know how to tell which way your version was installed, that is something a git user will need to run you through as I've only done the basics of git myself.

When I looked at our version, I could tell just from how sloppy the file structure was that we didn't use git. My predecessors copied it and made a mess of the file structure such that there were 3 copies of everything in both a production folder and a test folder. It was a nightmare getting it figured out and I just started from scratch when I upgraded to 3.0. Since I did the install for 3.0 myself, it was much easier to upgrade to 4.0.

[Schwen]

I haven't been able to figure out the version, yet. It's a virtual server, and I have a snapshot for it. So I can blow it up as much as I want, at least.

[Schwen]

So, still working this out. a git pull ends up giving me:
Pull is not possible because you have unmerged files.
Please, fix them up in the work tree, and then use 'git add/rm <file>'

as appropriate to mark resolution, or use 'git commit -a'.

Is there a way to use git to see all the files that need merging?

[Mark Swenson]

I'm not really a git expert, but I think that this StackOverflow post addresses the issue that you are having and explains it well: https://stackoverflow.com/questions/26376832/why-does-git-say-pull-is-not-possible-because-you-have-unmerged-files

The short answer seems to be the command: git status

Mark Swenson

IT Manager

Winnetka-Northfield Public Library District

[Schwen]

Ok, I seem to be getting a bit further, I can stash , then git pull, then git stash apply --index, finally git commit -a

From there running a second git pull says "Already up to date."

However, it doesn't seem to be connecting to the database anymore, which is on a different server. The settings seem there in config.yaml, however.

[Mark Swenson]

Presumably you're talking about the config.yaml in [Suma]/service/config (there's another one in [Suma]/web/config that doesn't do anything with database connections).

I'm not sure where your issue would be, but have you checked the log (in my config.yaml the log location is set to /var/log/suma and I'm guessing that's the default)?  That might tell you something about why the connection to the database server could be failing.

Mark Swenson

IT Manager

Winnetka-Northfield Public Library District

[Schwen]

Nothing seems to stand out in the logs. I tried to save a couple files such as config.yaml and then git pull. And while the operation still completes, and I restore the config, it's like the db isn't present. I suppose it could be how I am doing things, but I'm thinking something is being overwritten that is important. Is it possible a restart is needed after doing the git pull? It's on linux, so I wouldn't think so, but perhaps?

Maybe there is a way to replace the core files without a git pull? The install instructions are rather poor when it comes to an upgrade.

[Mark Swenson]

You certainly don't need to do a git pull.  I don't think I installed it that way.  It can be a convenient method for updating files though, which is probably why it's encouraged.

You can just do a straight download of the repository from git into a new directory and then copy the config files into place.  That would be something like:

wget https://github.com/suma-project/Suma/archive/refs/heads/master.zip

unzip master.zip

mv master my_new_suma_install (or whatever you are calling it)

Then you'd need to make sure the ownership and permissions are set right on the directories, and copy over the config files.  You'd probably want to rename the old directory "suma-old" and then rename "master" whatever your current suma directory is so you don't need to reconfigure Apache (or nginx or whatever you are using for serving http).

Mark Swenson

IT Manager

Winnetka-Northfield Public Library District

[Schwen]

I think I'll have to look into it that way. At the rate it's going, it might be easier to just do a fresh install that links back to the db.

[Schwen]

Well, I got the new master and moved it into place. I copied what I thought were the config files, including the config.yaml that has my db info. Same thing on the client web end. Address is reachable, but there appears to be no db info. I copied a couple different config.yamls to their respective locations. Everything is owned by apache. I also copied Globals.php and schema.sql. There must be 1 file I am missing elsewhere.

Also, on the new master, if I run a git pull, just to see what happens, I receive: fatal: Not a git repository (or any of the parent directories): .git

So, maybe that has something to do with it.

[Mark Swenson]

As I mentioned earlier, I'm not a git expert, but I know that it won't work that way, not unless you yourself know git well and can fool it.  It will only synchronize with a directory that it made.  When you choose to manually download a zip file and expand it, you are actively choosing not to use git.  git creates a bunch of files when you first synchronize with it, so you'd have to manually recreate that structure somehow.  If you really want to use git for updating you should not download the directory directly.  If you don't mind doing manual updates and hate using git, then this is the way to go.

As far as your actual problem, I'm not sure.  I'd make sure that the computer that you are using can connect to the MySQL server that you are using with the credentials that are in your config file to start, just to make sure that there isn't a problem outside of Suma configuration (I'd probably test this by running the mysql client on the Suma server computer).  Then I'd recommend looking through the Suma installation guide step-by-step to make sure that everything is where it's supposed to be.

I don't have any other ideas at the moment without a more concrete error, but it's possible that someone else on this forum might have an idea I haven't considered.

Mark Swenson

IT Manager

Winnetka-Northfield Public Library District

[Schwen]

Yeah, the db connection works, till I git pull or otherwise update the files. That's when it breaks. That's why I am thinking there is a config file somewhere in the suma directory. I looked at the guide, doesn't mean I didn't miss something, but I think I checked everything listed in the guide.

[Eric McEachern]

What error is being thrown? Either on screen or within the log files.

-Eric

On Jan 13, 2022, at 3:02 PM, Schwen <jon.sc...@gmail.com> wrote:

Yeah, the db connection works, till I git pull or otherwise update the files. That's when it breaks. That's why I am thinking there is a config file somewhere in the suma directory. I looked at the guide, doesn't mean I didn't miss something, but I think I checked everything listed in the guide.

To view this discussion on the web visit https://groups.google.com/d/msgid/suma-mobile-library-assessment-toolkit/e3f84c8e-275b-47b7-be77-5069352e709cn%40googlegroups.com.

[Mark Swenson]

In trying to guess in what's going on in your system, I went through the whole process of installing Suma on a different server.  Skipping over Apache configuration and the installation of required modules (in my case my server was missing php7.4-mysql which caused some headscratching near the end), this is pretty much the entire series of steps on an Ubuntu server to get a basic install going (I did skip some "chown" commands to change ownership on files copied using sudo):

/* Linux Commands */

cd /var/local/

sudo wget https://github.com/suma-project/Suma/archive/refs/heads/master.zip
sudo unzip master.zip
sudo mv Suma-master suma
sudo chown -R www-data:www-data suma
cd suma
sudo mkdir /var/www/htdocs/suma
sudo ln -s service/web/ /var/www/htdocs/sumaserver
sudo ln -s web/ /var/www/htdocs/suma/client
sudo ln -s analysis/ /var/www/htdocs/suma/analysis
sudo mkdir /var/log/suma

sudo chown www-data:www-data /
mysql -u root -p

/* MySQL commands */
CREATE DATABASE suma;
CREATE USER 'sumaadmin'@'localhost' IDENTIFIED BY 'password';
CREATE USER 'suma'@'localhost' IDENTIFIED BY 'password';
GRANT SELECT, INSERT, CREATE, DROP, DELETE, UPDATE, INDEX, ALTER on suma.* TO 'sumaadmin'@'localhost';
GRANT SELECT, INSERT, UPDATE, INDEX on suma.* TO 'suma'@'localhost';
FLUSH PRIVILEGES;
\quit

/* Linux commands */
mysql -u sumaadmin -p suma < /var/local/suma/service/config/schema.sql

cd service/web/config
sudo cp config-example.yaml config.yaml
sudo nano config.yaml

/* File edits - lines changed in file*/
--
SUMA_SERVER_PATH: /var/local/suma/service
SUMA_CONTROLLER_PATH: /var/local/suma/service/controllers
--

cd ../../../web/config/
sudo cp spaceassessConfig-example.js spaceassessConfig.js
cd ../../analysis/config/
sudo cp config_example.yaml config.yaml

sudo nano config.yaml

/* File edits */

---
[change URLs and email addresses]
---

cd ../../config/
sudo cp config-example.yaml config.yaml
sudo nano config.yaml

/* File edits - lines changed in file - since MySQL was running locally I didn't need to change server address */

---
user: suma
pword: [password]
path: /var/log/suma
---

After that, going to: http://[server url]/sumaserver/admin/ and login and start editing locations.

If that's not helpful, it might help us figure out what's going wrong if you could provide a little more information about what you are seeing that makes you certain that you aren't getting a database connection.  The basic installation process is (compared to many other things I've worked with) pretty simple.

Mark Swenson

IT Manager

Winnetka-Northfield Public Library District

[Schwen]

Is there a restart command for suma? I mean, sure I can reboot, but I'm just wondering if there is a command of sorts.

[Mark Swenson]

Suma is essentially a database driven website.  So you don't restart it, any more than you would restart a specific website you were hosting on a server (which normally consists of a bunch of documents that get interpreted).  You can restart your web server and you can restart the database server (although there's not a lot of reason to do the latter in my experience), but you cannot choose to restart a single website.

Restarting Apache2 varies by server that you're running it on.  Most commonly in linux it's:

sudo service apache2 restart

 or

sudo systemctl restart apache2

You can also choose to "reload" Apache instead of restart it, which tends to be a bit quicker and refreshes small changes in site configuration.

Different Linux versions will use different systems for handling running services and restarting them.  My experience is primarily with Debian variants of Linux.  Others might use different commands for restarting the Apache2 server.

Restarting a MySQL server would follow a similar formulation, e.g.:

sudo service mysql restart

or

sudo systemctl restart mysql

Suma does rely on some other components, PHP being a primary one.  PHP doesn't run on its own though and anything being handled by PHP is restarted when you restart an Apache (or any other) web server.

Mark Swenson

IT Manager

Winnetka-Northfield Public Library District

[Schwen]

Anyways, after going through a slew of things and copying files from old to new, I think it works. I used diff -rq on the directories to see which were different, and then I could check them out. Ultimately, I think the new install, didn't like the old config file, for whatever reason. Created a brand new /service/config/config.yaml, then modified the required settings. It appears to work, so far. I have the user coming to check it out to make sure everything actually works, but the old data seems like it might be there.

I had restarted apache after making changes before, but I never noticed a change, so I wasn't sure if there was something else.