Contents

Installation

Installation

Supported operating systems

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

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 in Debian-like Linux with:

    sudo adduser --system --group nextpyp

    If you’re using RHEL-like Linux, try:

    sudo adduser --system --user-group nextpyp
  • 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:

Before installing the packages, you will need first to enable the EPEL repository, if it was not enabled already:

sudo dnf install -y epel-release

Then you can install the packages:

sudo dnf install -y apptainer wget

Install wget:

sudo apt-get install -y wget

Download debian package for Apptainer:

wget https://github.com/apptainer/apptainer/releases/download/v1.1.0-rc.2/apptainer_1.1.0-rc.2_amd64.deb

Install Apptainer:

sudo apt-get install -y ./apptainer_1.1.0-rc.2_amd64.deb

Step 3: Download and run the installation script

First, create the folder where nextPYP will be installed. Something like /opt/nextPYP works well. Then navigate to the folder in a shell session:

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

Then, download the installation script:

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

Note

Other versions can be installed by downloading an installation script by its version number. If you wanted to specifically install version 0.5.0, you would download the installation script at https://nextpyp.app/files/pyp/0.5.0/install.

Feel free to inspect the installation script. It’s fairly simple. Once you’re confident that it does what you want, mark it executable and run it with administrator privileges. You’ll need to supply the name of the service account as the $PYP_USER environment variable.

sudo chmod u+x install
sudo PYP_USER=nextpyp ./install

If the installer gives an error like $username is not a valid group, then you’ll need to set the group for the service account too, using the $PYP_GROUP environment variable:

sudo PYP_USER=nextpyp PYP_GROUP=services ./install

The install script will download the rest of the needed software components and set them up. Assuming fast download speeds, the installation script should finish in a few minutes.

Step 4: Check installation results

Among other things, the installer created a systemd deamon named nextPYP to start and stop the application automatically. The daemon should be running now. Check it with:

sudo systemctl status nextPYP

If all went well, you should be greeted with a response similar to the following.

● 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 also access the website directly from the shell:

wget http://localhost:8080 -O -

Running the wget command above 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 (i.e., with a keyboard and a monitor), then you can visit the website in your browser now at http://localhost:8080.

Note

If you’re logged into the server remotely over SSH, you won’t be able to visit the website in your browser just yet. Remote network access to the website is disabled by default. To enable remote access, head to Next steps.

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.

If you’re not logged into the server locally (i.e., with a keyboard and monitor), then you’ll need to enable remote access to use the website from the network. Follow these instructions to configure remote network access.

If you need to allow multiple 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.

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.

Upgrading to a new version

To upgrade to a new version, stop nextPYP and simply re-run the installation:

# stop nextPYP
sudo systemctl stop nextPYP

# stop the reverse proxy (only required if you configured remote access through untrusted networks)
sudo systemctl stop nextPYP-rprox

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

# re-run the installation
sudo PYP_USER=nextpyp ./install

# re-install the reverse proxy (only if you configured remote access through untrusted networks)
sudo chmod u+x install-rprox
sudo PYP_DOMAIN=myserver.myorganization.org ./install-rprox

After this, you should be able to access the application the same way you did before the upgrade.

previous

nextPYP

next

Enable remote access