Zoph Setup and Use

Tips and Tricks
2

@sunil, @nbenedek, @jvalleroy, @njoseph - this instruction has all the workarounds related to the Zoph issues I’ve raised this week.

Bookworm Instructions

This is the Debian Bookworm with Zoph 1.0.1-3 thread which applies to FreedomBox on Debian Stable as of December 2024.

Upstream Project

Their documentation is rather good. You’ll want to be reading this soon!

What can I expect from Zoph in FreedomBox Bookworm?

Zoph is a FreedomBox application that helps you store, organize, and share photos. Is it a replacement for the big photo website? Not completely and mainly for the lack of rich editing tools you will find in “free-as-in-beer” consumer sites or professional photography portal solutions. Zoph does offer good photo upload, download, sharing and organization capability which is “free-as-in-freedom.” It is worth a try, but at this point you’re going to have to have to do a little work. When you do these things you’ll find Zoph to be a reasonable option for what it does.

What about editing?

Zoph can rotate photos in increments of 90 degrees to get the orientation right. That’s about the end of editing with Zoph. There are many truly great free software options available for photo retouching with the most full-featured option probably being GIMP. Your editor won’t be integrated into the web service, but if you are willing adjust your edit/import workflow you won’t be missing much. With FreedomBox you could also work with file sharing tools such as Samba or NFS to work out an ‘edit in place,’ setup, but that is beyond the scope of this post. It’s possible for the intermediate to advanced Debian user. If that’s not you today - you will be if you get that sorted!

I’ve already tried Zoph, and I had a lot of trouble.

Me too. I’ve been slaving over this for days to figure it out - and I think it’s pretty close to right. That’s what I’m sharing here! Read on and try it again!

This is the robust way to set up Zoph!

We’re going through a number of steps here throug FreedomBox, then the command line, and finally in the Zoph web application.

Install and setup from the FreedomBox app page - but don’t start using it

  1. Install Zoph from the FreedomBox apps page normally. don’t hit the “Setup” button after installation yet.
  2. You’ll want to select your ordinary user account as the Zoph administrator before you hit the “Setup” button on the Zoph app management page in FreedomBox. I don’t believe it matters if this user is a FreedomBox system administrator.
  3. Stop! Don’t hit the “Launch web client” button or hit the Zoph application tab on the FreedomBox home page yet.

Now we’re going to do some work in the command line. You’ll want to use the Cockpit terminal or SSH to connect to your FreedomBox.

We are going to make some Zoph directories manually. The reason for this is that without some fine tuning you are going to run into a problem if you switch between the Zoph web application and the zoph command line tool. You should be able to use both, and we’ll get that right.

We are going to use sudo here, so you’ll need to be logged in as a FreedomBox administrative user. where you see a ‘$’, that is your command prompt and you will type in everything following the $, but not the $ itself. This will look somewhat like what you’ll see on your terminal.

  1. Create the directories you need, change owners and groups, set permissions

    $ cd /var/lib/zoph
    $ sudo mkdir mid thumb trash upload upload/mid upload/thumb
    $ sudo chown www-data:zoph mid thumb trash upload upload/mid upload/thumb
    $ sudo chmod 0770 mid thumb trash upload upload/mid upload/thumb
    $ sudo chmod g+s mid thumb trash upload upload/mid upload/thumb

  2. Add users www-data and any Zoph users to the zoph group

    $ sudo usermod -G zoph -a www-data
    $ sudo usermod -G zoph -a <zoph using FreedomBox account name>

    For my own user it looks like this: $ sudo usermod -G zoph -a joseph

That’s all of the command line work!

Now you can start the Zoph web application.

There are three parts to the Zoph tasks: configuration, first user setup, and then next user(s) setup. Last, we’ll create an album to put some pictures in.

Zoph Configuration

Go immediately to the admin menu and then configuration. We’re going to set a bunch of values in here. If I put something in bold, just do it that way. If it is not bold, you can experiment with different values later. Later you can read the manual about why I set things in bold.

  • Screen width: 92%
  • CLI user: Autodetect
  • Trash dir: trash
  • Resize parallel: Same as # of CPU cores. I have 2.
  • File mode: RW for user/collection… 0660
  • dir mode: RW for user/collection… 0770
  • CLI copy on import: Checked (for no confusion - read the manual on this)
  • Rotation: Checked
  • Rotate command: jpgegtran (other option is lossy, read the manual)
  • Salt for sharing full size images: Hit Generate
  • Salt for sharing mid size images: Hit Generate
  • Time format: H:i:s A
  • Hit the submit button at the bottom.

After you get comfortable with this you can do some experimentation. This is a good starting point. You may need to change time format based on your region - this is good for North America.

First User Setup

We’re going to be moving through a bunch of menus from the top menu bar here. Each page will have a submit/save/update type button to finalize your change. Click that before moving on to each section. Sometimes we go back and forth - there is a method to the madness.

people

You will see an unknown user. Edit that and fill out your name and any other fields you care to.

admin / users

Edit your username and set the person field selecting your name from the people record.

admin / groups

  • Make a group for your Zoph users, name it a"Zoph owners" for now - you can change its name later.
  • Edit the group and add your Zoph user as a Zoph owners member.

albums

Create an album named “user’s lightbox”. Do not grant any access to this album. (it’s in the manual) (also, substitute your username for user)

admin / users

Edit your user and set the lightbox album to the album you just made.

Your first user is set up! The rest is just details and learning to use the application.

Next user(s) setup

If you have more than one Zoph user you can consider this setup for the next users. In my case I want the other user to also be an administrator. Administrators are able to create albums, define people, set categories. It’s all practical stuff - so if more than one person is adding to your Zoph you’ll probably want to start this way. When you get to the point that you are creating User class users you are getting to be an expert.

people

Create a new person corresponding to your next user.

album

Create a new lightbox album for your next user.

admin / users

Create a new user

  • Zoph username must match the FreedomBox username exactly
  • Set the Person field for the user
  • Password must be empty
  • Set class to Admin
  • Set the lightbox field for the user
  • submit/save

admin / groups

Add your new user to the “Zoph owners” group you created.

Create an Album

Go to albums now and create a new photo album. Name it, “My new photo album.” You can change the name later. Hit the insert button. The window will change and you’ll see Album permissions. Select “Zoph owners” from the drop-down menu, keep access level 5, and make writable Yes.

We’re done!

You are now ready to import some photos and add them to My new photo album. I think this setup is complete enough to learn your way through Zoph smoothly. This will avoid some major headaches:

  1. Zoph does not delete photos. If you don’t set up trash I’m not sure how you’ll figure out what photos you can delete if your storage fills up. Trash makes that easier - just delete files from /var/lib/zoph/trash
  2. Zoph does not delete photos. So if you delete a photo from Zoph, and then try to import it again you will have an error and won’t be able to get that photo in Zoph again. trash fixes that, too.
  3. If you use command line and web interface to import photos it will start failing if you did not create the folders and set permissions as we did earlier.
  4. Zoph and FreedomBox don’t set up any users after the first. These instructions avoid a problem where you think you should be logged in, but are told that you gave the wrong user name or password.

I hope you’re able to work productively with Zoph after this! Here are some final thoughts as you get to using Zoph.

Use Hierarchies

It looks like hierarchy arrangements are going to be very useful. Let me give you some examples to get you thinking in this direction.

Places

You have a home, but you have probably had more than one home.

  • Make a place called Home, leave everything blank.
  • You can make a new place - “Childhood Home” with parent location of “Home”
  • You can make a new place - “Denver” with a parent location of “Home”
    • You can make an "Oak Street Apartment place with a parent of “Denver”
    • You can make a “First Avenue Apartment” place with a parent of “Denver”

Now when you organize and search you could search for Home for any home, Denver for any of your Denver apartments, or Oak Street Apartments for pictures from your epic party there.

Albums

I’m not sure if this is the best way, but it is what I’m doing.
I made an album named, “Photo Albums”. Under that we’ll create the rest of the photo albums that we’d like in any hierarchy arrangement. I did this because it looks like I can apply permissions to all of these at once. Maybe that will save some clicks. I did the same with lightboxes in a hierarchy.

Circles

Circles are groups of people which you’ll want to search for. “Family,” “School Friends,” “Softball Team.” I’m unsure if you can make circles of circles - I have not tried that yet. If so, it will probably be helpful:

  • Family
    • My Family
    • Cousins
    • Aunts and Uncles

Tell me how it works for you, and what you’re doing. I hope it’s great!