Overview¶

Supported operating systems¶

nextPYP has been tested and works on the following operating systems:

• Rocky Linux 8.6

• CentOS 7

• Ubuntu 22.04.1 LTS

• Debian 12 Bookworm

These instructions refer to the installation of nextPYP’s’ web interface. If you want to install the PYP command line interface, follow these instructions instead.

Step 1: Prerequisites for installation¶

• Service account

  nextPYP requires a service account to run the web server process. Because this user account runs a web server which may be exposed to external networks, like the public internet, the service account should not have administrative privileges.

  Note

  If you intend to attach a SLURM cluster later on, this account should have access to the required network resources, like the SLURM login node, and a shared filesystem.

  If you don’t have a service account ready already, and you only need it to work on the local machine, you can create one with:

  sudo useradd --system --user-group nextpyp
  

• Storage space

  Cryo-ET and cryo-EM data requires significant amounts of storage space – on the order of terabytes. At the very least, you’ll want to have access to a multi-terabyte partition (either an SSD mounted locally or a large capacity network-mounted share). nextPYP does best with fast local storage, but it can use slower remote storage as well. If you configure nextPYP to store its data on a typically-sized 10s of gigabyte operating system partition, you’ll very quickly run out of space.

  Tip

  You can quickly see what storage devices your system has and how much space is available by running the df command:

  df -h
  

• Access to GPUs (optional)

  GPUs are only required to execute certain processing steps in nextPYP (e.g.: train neural networks for particle picking, run MotionCor3 for frame alignment or Aretomo for tilt-series alignment and reconstruction). nextPYP uses Apptainer which natively supports NVIDIA CUDA & AMD ROCm, but we have only tested it with NVIDIA GPUs. If you have problems using AMD ROCm GPUs, please contact us.

Step 2: Install operating system packages¶

The only packages needed are Apptainer (formerly Singularity) and wget. Instructions for installing then vary by operating system:

sudo apt-get install -y wget

wget https://github.com/apptainer/apptainer/releases/download/v1.3.4/apptainer_1.3.4_amd64.deb

sudo dpkg -i apptainer_1.3.4_amd64.deb

sudo dnf install -y epel-release

sudo dnf install -y apptainer wget

Step 3: Download and run the installation script¶

cd ~/
mkdir nextPYP
cd nextPYP

wget https://nextpyp.app/files/pyp/latest/install

chmod u+x install

./install

sudo mkdir -p /opt/nextPYP
cd /opt/nextPYP

sudo wget https://nextpyp.app/files/pyp/latest/install

sudo chmod u+x install

sudo PYP_USER="service_acct" PYP_STORAGE="/large-storage/nextpyp" ./install

sudo PYP_USER="service_acct" PYP_SHARED_DATA="/nfs/nextPYP/data" ./install

The install script will download the rest of the needed software components and set them up. Total download sizes are in the tens of gigabytes, so on a fast internet connection, the installation script would need at least a few minutes to finish.

Step 4: Check installation results¶

./nextpyp start

Reading config.toml using CLI tool ...
Host Processor started pid=1291 (/media/micromon/run/host-processor)
Configuring environment ...
Starting singularity container ...
INFO:    instance started successfully

./nextpyp stop

sudo systemctl status nextPYP

● nextPYP.service - nextPYP
  Loaded: loaded (/usr/lib/systemd/system/nextPYP.service; enabled; vendor preset: disabled)
  Active: active (running) since Thu 2022-08-11 10:14:57 EDT; 4h 5min ago
Main PID: 2774 (starter-suid)
    Tasks: 91 (limit: 23650)
  Memory: 708.3M
  CGroup: /system.slice/nextPYP.service
          ├─2774 Singularity instance: nextpyp [nextPYP]
          ├─2775 sinit
          ├─2793 /bin/sh /.singularity.d/startscript
          ├─2796 /bin/sh /opt/micromon/init.sh
          ├─2802 /usr/bin/python2 /usr/bin/supervisord -c /etc/supervisor/supervisord.conf
          ├─2893 /bin/sh /opt/micromon/bin/micromon.sh
          ├─2894 /usr/bin/mongod --config /tmp/mongod.conf
          └─2895 java -Xmx2048M @bin/classpath.txt io.ktor.server.netty.EngineMain

You can test that the nextPYP website is running directly from the shell:

wget http://localhost:8080 -O -

Executing this command should return a response like the following:

--2023-11-15 11:46:35--  http://localhost:8080/
Resolving localhost (localhost)... ::1, 127.0.0.1
Connecting to localhost (localhost)|::1|:8080... connected.
HTTP request sent, awaiting response... 200 OK
Length: 353 [text/html]
Saving to: ‘STDOUT’

-                                    0%[                                                                 ]       0  --.-KB/s               <!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>nextPYP</title>
    <link rel="icon" type="image/png" href="favicon.png">
    <script type="text/javascript" src="main.bundle.js"></script>
</head>
<body>
<div id="mmapp"></div>
</body>
</html>
-                                  100%[================================================================>]     353  --.-KB/s    in 0s

2023-11-15 11:46:35 (47.7 MB/s) - written to stdout [353/353]

If you get errors instead of something similar to the responses above, then the application did not start up successfully. You can look for clues as to what went wrong by checking the various log files. See troubleshooting for more details.

If you’re logged into the server locally (e.g., with a keyboard and a monitor or some kind of remote desktop software like VNC), then you can visit the website in your browser now at http://localhost:8080.

Step 5: Configure your data folders¶

nextPYP uses containerization technology to help keep the install process as simple as we can make it, but that comes with some tradeoffs. One tradeoff is that since containerized apps operate inside of an isolated virtual filesystem, these apps can’t see all of the files in your real filesystem by default. Meaning, nextPYP won’t be able to see your Cryo-EM/ET data by default either.

To get nextPYP to see your data, you’ll have to “bind” your data path(s) into the container’s filesystem. You can do this by adding your data folder paths to the nextPYP configuration file.

The installer created a configuration file for you called config.toml and there’s a symlink to it in your installation folder. The configuration file is written in a configuration language called TOML. TOML is pretty similar to JSON, if that’s familiar to you, but TOML is a bit nicer to use for this kind of thing.

To add (aka “bind”) your data folders into nextPYP’s container, edit the config.toml file with your favorite text editor. Under the [pyp] section of the configuration file, look for a line that looks like this:

binds = []

In, TOML, [] is an empty array (or list), so by default the binds list is empty. To bind your data folder(s), add the paths (as strings) to the list. That might look something like this:

binds = ['/path/to/my/data']

Or this:

binds = [
  '/big-storage/cryo-data',
  '/other-big-storage/cryo-data'
]

After making changes to your configuration file, restart the application to apply the changes:

./nextpyp stop
./nextpyp start

sudo systemctl restart nextPYP

There are many other configuration options beyond the ones described here. See the full documentation for the configuration file to learn about all of the other configurable settings.

Next steps¶

You can start using the application right away. By default, it’s installed in single-user mode, runs computation jobs on the local server, and is only accessible locally. This is the simplest configuration for the application, but you can enable other configurations using the linked instructions below.

• Enable remote access

  If you’re not logged into the server locally (e.g., with a keyboard and monitor or some kind of remote desktop software like VNC), then you’ll need to enable remote access to use the website from the network. Follow these instructions to configure remote network access.

• Enable multiple users

  If you need to allow different people to use the application, but want them to have separate projects and storage locations, follow these instructions to set up multi-user mode.

• Attach a SLURM cluster

  For large processing jobs, using a compute cluster can speed up results significantly. These instructions show how to attach a SLURM cluster to your installation. If you installed nextPYP using the PYP_SHARED_DATA and PYP_SHARED_EXEC options, you’ll want to follow this step to connect nextPYP to your SLURM cluster.

Upgrading to a new version¶

Step 1: Pre-installation steps (conditional)¶

Step 2: Run the installation script¶

To upgrade to a new version, stop nextPYP, download the new installer, run it, and then re-start nextPYP.

# stop nextPYP
./nextpyp stop

# download the new installer and mark it executable
wget https://nextpyp.app/files/pyp/latest/install -O install
chmod u+x install

# run the new installer to upgrade
./install

# stop nextPYP
sudo systemctl stop nextPYP

# download the new version's installer
sudo wget https://nextpyp.app/files/pyp/latest/install -O install
sudo chmod u+x install

# run the new install script
# If upgrading from v0.6.5 or earlier, you will need to set the PYP_SHARED_EXEC variable, e.g.:
# sudo PYP_SHARED_EXEC="/storage/nextPYP/sharedExec" ./install
sudo ./install

Step 3: Post-installation steps (conditional)¶

As a general rule, the installer won’t make any changes to your existing configuration file, or delete any potentially important files. So, some upgrades may require you to take these steps manually.

If manual steps are needed after an upgrade, you’ll see a message like the following in your console:

===============================================================================
|  BUT WAIT! There's still a bit more you need to do                          |
|-----------------------------------------------------------------------------|

See below for more information about manual upgrade steps that are specific to each version of nextPYP.

Step 4: Start nextPYP again¶

After the installer has finished, and you have completed any manual post-installation steps, start nextPYP again:

./nextpyp start

systemctl status nextPYP

sudo systemctl start nextPYP

Getting Help¶

Getting nextPYP installed and working correctly can be tricky sometimes, especially since everyone’s needs are just a little different. We’ve done our best to build an install process that’s flexible enough to work in many different environments, but sometimes things still might not work out perfectly.

If you have questions, need clarification on any of the installation options, or are just looking for a little help getting through the installation, visit the Support page for a list of available support resources.