Fast path
Quick start protocol
-
01
Unpack the release
Terminal
tar -xzf coco.tar.gz
cd coco
-
02
Install the managed runtime
Terminal
bin/coco-install-runtime.sh
-
03
Start CoCo
Terminal
java -jar backend/<backend runnable jar>
-
04
Open the interface
Browser
http://localhost:8078
Before install
Prerequisites
Required runtime tools:
- Java 8 or above
- Access to CryoSPARC, if using CryoSPARC-backed jobs
- Access to RELION, if using RELION-backed jobs
CoCo itself is packaged as a Spring Boot jar with the built frontend embedded. CryoSieve and CryoPROS use CoCo's managed runtime installed from runtime-packs/coco-runtime.tar.gz; users should not prepare separate CryoSieve or CryoPROS Python environments.
Release archive
Unpack the release
Given the release artifact coco.tar.gz, unpack it and enter the release directory.
Terminal
tar -xzf coco.tar.gz
cd coco
Expected layout:
Layout
coco/
├── bin/
│ └── coco-install-runtime.sh
├── backend/
│ └── <backend runnable jar>
├── modules/
│ ├── cryosieve/
│ └── cryopros/
├── runtime/
├── runtime-packs/
│ └── coco-runtime.tar.gz
├── .gitmodules
└── modules.lock
Not included by design
The CryoSieve tutorial movie modules/cryosieve/cryosieve_video_tutorial.mp4 is intentionally not included in the package and is not required for CoCo runtime.
Managed environment
Install the managed runtime
From the unpacked coco/ directory, install the unified CryoSieve and CryoPROS runtime.
Terminal
bin/coco-install-runtime.sh
This unpacks runtime-packs/coco-runtime.tar.gz, runs conda-unpack, validates the CryoSieve and CryoPROS command-line tools, and prepares the managed runtime under:
Runtime path
runtime/envs/coco-runtime
It also writes the runtime profile consumed by CoCo:
Profile path
runtime/coco-runtime-profile.json
If the runtime already exists, validate it and rewrite the profile:
Check existing runtime
bin/coco-install-runtime.sh --check-only
To remove and reinstall the runtime:
Reinstall runtime
bin/coco-install-runtime.sh --force
Use the jar found under backend/.
Terminal
java -jar backend/<backend runnable jar>
You may also start from the parent directory, which is useful when existing project or auth data is relative to that working directory.
Parent directory
java -jar coco/backend/<backend runnable jar> --server.port=8078
In packaged releases, CoCo first checks ./runtime/coco-runtime-profile.json, then infers coco/runtime/coco-runtime-profile.json from the jar location. If needed, override the runtime profile explicitly.
Runtime override
java -Dcoco.runtime.profile=/absolute/path/to/coco/runtime/coco-runtime-profile.json \
-jar coco/backend/<backend runnable jar> --server.port=8078
The default backend port is 8078. Open:
Browser
http://localhost:8078
Default application settings are bundled in the jar:
application.properties
server.port=8078
app.auth.mode=DISABLED
To override settings at runtime, provide Spring Boot properties. For example, to use another port:
Custom port
java -jar backend/<backend runnable jar> --server.port=8080
To enable auth, use one of the supported modes:
Bootstrap auth
java -jar backend/<backend runnable jar> \
--app.auth.mode=BOOTSTRAP \
--app.auth.bootstrap-admin-username=admin \
--app.auth.bootstrap-admin-password=change-me
Supported auth modes:
DISABLEDBOOTSTRAPENFORCED
When auth is enabled, file-based users are stored under auth/users.json, relative to the process working directory.
Auth flow
Login verification page
When auth is enabled, protected pages redirect unauthenticated users to /login-verification. Use the configured account and password to sign in.
For a fresh release test with bootstrap auth:
Bootstrap test
java -jar backend/<backend runnable jar> \
--server.port=8078 \
--app.auth.mode=BOOTSTRAP \
--app.auth.bootstrap-admin-username=admin \
--app.auth.bootstrap-admin-password=ChangeMe123 \
--app.auth.bootstrap-admin-must-change-password=true
Then open:
Browser
http://localhost:8078/home
/home redirects to /login-verification.- Sign in with account
admin and password ChangeMe123.
- If
mustChangePassword is true, CoCo redirects to /change-password.
- After changing the password, CoCo opens
/home.
BOOTSTRAP only creates the bootstrap admin when auth/users.json is missing or empty. If auth/users.json already contains users, changing app.auth.bootstrap-admin-password does not overwrite the existing admin password.
To reset the bootstrap admin password intentionally:
Reset admin password
java -jar backend/<backend runnable jar> \
--server.port=8078 \
--app.auth.mode=BOOTSTRAP \
--app.auth.bootstrap-admin-username=admin \
--app.auth.reset-admin-password=ChangeMe123
After reset, sign in with admin / ChangeMe123. CoCo will require a password change.
Disposable local tests only
You can remove the test user file and bootstrap again only for disposable local tests.
Local reset
rm -f auth/users.json
java -jar backend/<backend runnable jar> \
--server.port=8078 \
--app.auth.mode=BOOTSTRAP \
--app.auth.bootstrap-admin-username=admin \
--app.auth.bootstrap-admin-password=ChangeMe123
Do not delete auth/users.json in production unless you intend to remove the stored users.
Environment check
Configure external dependencies
Only these should appear as user-facing external dependencies in Environment Check:
After starting CoCo:
- Open Settings.
- Go to Environment Check.
- Confirm the Managed CoCo Runtime card shows
READY.
- Configure CryoSPARC and RELION command/environment snippets.
- Verify both checks pass.
The managed runtime status is also available at:
Endpoint
GET /api/open/settings/managed-runtime
CryoSieve and CryoPROS are built-in modules. They should not appear as top-level external dependency cards. Their module metadata and resources are packaged under modules/, and their CLI environment is provided by runtime/envs/coco-runtime.
Compute lanes
Configure SLURM lanes
CoCo lanes describe how jobs are submitted to a compute environment. For a SLURM lane, the lane should contain the fixed SLURM template for that queue or partition, while per-job resources such as GPU count are chosen in each job dialog.
Single-node SLURM lane with job-selected GPU count
For a single-node GPU lane where different jobs may request different GPU counts, configure the lane as a capacity limit instead of a fixed GPU request.
- Max GPUs: set this to the maximum number of GPUs a job may request on this lane. For example, if one node has 4 GPUs, set
Max GPUs = 4.
- Cluster Template: include only fixed SLURM settings for this lane, such as partition, memory, stdout, and stderr paths.
- Local Environment: include shell setup lines such as
module load commands.
- Do not put fixed node, task, or GPU resource requests in the lane template.
Avoid these lines in the SLURM lane template:
Avoid fixed requests
#SBATCH -N 1
#SBATCH --nodes=1
#SBATCH -n 1
#SBATCH --ntasks=1
#SBATCH --gpus=1
#SBATCH --gpus-per-node=1
#SBATCH --gpus-per-task=1
#SBATCH --gres=gpu:1
CoCo generates those resource lines dynamically from the job dialog. For GPU jobs, the job dialog determines the requested GPU count, and CoCo writes a single-node SLURM header like:
Generated by CoCo
#SBATCH -N 1
#SBATCH --ntasks=<task-count>
#SBATCH --gpus=<job num_gpus>
export COCO_NUM_GPUS=<job num_gpus>
export COCO_NPROC_PER_NODE=<job num_gpus>
Example SLURM lane for a single-node GPU partition with up to 4 GPUs:
Cluster template
#!/bin/bash
#SBATCH --partition=<gpu_partition>
#SBATCH --mem=128G
#SBATCH --output=coco-%j.out
#SBATCH --error=coco-%j.err
Set:
Lane capacity
Max GPUs: 4
Then each job chooses its actual GPU count in the job creation dialog:
- job requests
1 GPU, CoCo adds #SBATCH --gpus=1
- job requests
2 GPUs, CoCo adds #SBATCH --gpus=2
- job requests
4 GPUs, CoCo adds #SBATCH --gpus=4
If the job requests more GPUs than the lane's Max GPUs, CoCo rejects the submission.
Example Local Environment:
Local environment
module purge
module load cuda/12.1
module load relion
For CryoSieve and CryoPROS jobs, do not activate a separate Python or conda environment in the lane. CoCo activates the managed runtime automatically.
Module state
Verify built-in modules
The package includes module metadata for:
You can verify module state through the module API after startup:
Module APIs
GET /api/open/modules
GET /api/open/modules/installed
GET /api/open/modules/job-types
GET /api/open/modules/job-type-modules
Expected job families include:
PARTICLERESTACK_PARTICLESRECONSTRUCTCRYOSIEVECSREFINECSRHBFACTORCRYOPROS_PREPCRYOPROS_TRAINCRYOPROS_GENERATE
Runtime rules
Managed runtime behavior
Jobs that require the managed runtime include:
RESTACK_PARTICLESCRYOSIEVECSREFINECSRHBFACTORCRYOPROS_PREPCRYOPROS_TRAINCRYOPROS_GENERATE
Draft creation and editing are allowed when the runtime is missing, so users can prepare jobs before installation. Submit Now and existing draft submit are blocked until the runtime status is READY. Generated bash and SLURM scripts automatically activate runtime/envs/coco-runtime; for managed jobs, any old activationCmd value is ignored to avoid activating a different environment.
Release checks
Runtime workflow checks
After installation, test these flows in a real project:
- Import a
PARTICLE job.
- Create
RESTACK_PARTICLES from PARTICLE.
- Create
RECONSTRUCT from PARTICLE or RESTACK_PARTICLES.
- Create
CRYOSIEVE from PARTICLE or RESTACK_PARTICLES.
- Create
CSREFINE and CSRHBFACTOR from CRYOSIEVE.
- Create
CRYOPROS_PREP from PARTICLE or RESTACK_PARTICLES.
- Create
CRYOPROS_TRAIN from CRYOPROS_PREP.
- Create
CRYOPROS_GENERATE from CRYOPROS_TRAIN.
- If using CryoSPARC export, enable export in
CRYOPROS_GENERATE and confirm export_cryopros.py is resolved from the CryoPROS module resource or classpath fallback.
Troubleshooting
Common release checks
Port already in use
Start on another port:
Terminal
java -jar backend/<backend runnable jar> --server.port=8080
Managed runtime is MISSING, ERROR, or INCOMPLETE
Run from the unpacked coco/ directory:
Check runtime
bin/coco-install-runtime.sh --check-only
If validation fails because files are missing or stale, reinstall:
Force reinstall
bin/coco-install-runtime.sh --force
Then restart or refresh CoCo and check Settings → Environment Check → Managed CoCo Runtime.
CryoSPARC or RELION commands fail
Reopen Settings → Environment Check and verify the configured shell snippets. New lanes should use external dependency environment setup only; CryoSieve and CryoPROS are handled by the managed runtime.
CryoSieve movie is missing
This is expected. cryosieve_video_tutorial.mp4 is intentionally excluded from the release package and is not required for CoCo runtime.
Module resources are missing
Check that the unpacked release still contains:
Required resources
modules/cryosieve/module.yaml
modules/cryosieve/jobTypeMapping.json
modules/cryopros/module.yaml
modules/cryopros/jobTypeMapping.json
modules/cryopros/scripts/export_cryopros.py
modules.lock
Fresh source clone cannot fetch submodule commit
If installing from source rather than from coco.tar.gz, make sure the submodule commits recorded in modules.lock have been pushed to their remotes. Otherwise git submodule update --init --recursive or packaging/validate-modules.js remote reachability checks may fail.
