Skip to content

British-Oceanographic-Data-Centre/Argo-Toolbox

BranchesTags

Repository files navigation

Argo Toolbox API

A step‑by‑step guide to install, run, and explore the Toolbox API locally.
This documentation is tailored for non‑technical users, with simple instructions and no prior Docker experience required.

🚀 Quick start

If you already have Docker and Git configured on your local machine, you can just follow these steps:

  • clone this git repository :

    git clone https://github.com/amrit-eu/Argo-Toolbox.git
cd Argo-Toolbox

  • rename file .env.demo in .env.

  • run docker compose to launches services :

    docker compose up -d

🖥️ Detailed local Deployment Guide

This section provides installation instructions for Windows, Mac, and Linux. Follow the steps relevant to your operating system.

🛠 Prerequisites

Regardless of the operating system, you will need Docker and Git.Regardless of the operating system, you will need Docker and Git.

A desktop UI to create,manage and run all your docker containers.

Pick any one option for local testing.

  • Option A — Podman Desktop (recommended): If you have not installed, download and install Podman Desktop, open it, and use the GUI to run the container (instructions below).
  • Option B — Docker Desktop: If you have not installed, download and install Docker Desktop, open it, and use the GUI to run the containers (instructions below).

1.🦭 Podman desktop

You can install Podman Desktop on.

If you prefer using docker desktop then follow steps to install docker desktop(step 2) else move on to step 3.

2.🐳 Docker desktop

2. Install Git

📥 Clone the Repository

Open Terminal (Linux and Mac) or Windows Terminal (Windows) and run:

git clone https://github.com/amrit-eu/Argo-Toolbox.git
cd Argo-Toolbox

This downloads the Toolbox code onto your computer.

⚙️ Configure the Environment

  1. In the project folder, locate:

    .env.demo

  2. Create a copy named:

    .env

  3. If you are comfortable with Docker and wish to customise the configurations, Open .env using your favorite text editor.

  4. You can adjust values for your needs (look at .env.docs file that describe configurations).

#file checker API configuration
FILECHECKERAPI_IMAGE=ghcr.io/oneargo/argoformatchecker/python-api
FILECHECKERAPI_IMAGE_TAG=latest

#decoder API configuration
ARGODECODERAPI_IMAGE=boilerplateapi # to change with decoder image
ARGODECODERAPI_IMAGE_TAG=latest
DECODER_USER_UID=1000
DECODER_USER_GID=1000

#jupyterlab configuration :
JUPYTERLAB_IMAGE=quay.io/jupyter/datascience-notebook
JUPYTERLAB_IMAGE_TAG=python-3.13
JUPYTER_USER_UID=1000

#webserveur NGINX configuration
WEBSERVER_HOST="127.0.0.1"
WEBSERVER_PORT=8080

#Configure which service to enable (decoder,checker,jupyter) separated by a comma. will be run with 'docker compose up'
COMPOSE_PROFILES=decoder,checker,jupyter

Webserver will always be enabled as it is necessary to access others services.

Warning : An issue prevents the web server from starting if the Jupyter service is not running. For the moment keep `jupyter` in the list of services in `COMPOSE_PROFILES`.

The argo_nginx.conf.template file is needed and must not be changed.

▶ Launch Services (No Terminal Expertise Needed)

You can run the Toolbox API locally using either podman Desktop or Docker Desktop. Pick the option that matches what you installed on your computer.

💼 Before running the containers you will need the following.

  • Clone of the Argo toolbox repository.
  • All the configuration setup correctly.
  • Docker desktop or podman desktop installed.

if you do not have the repository containing the toolbox please clone it.

If using podman desktop

  1. Launch podman desktop

  2. You will notice a compose.yml in the toolbox. Run the following command in a terminal to pull all the required images.

    podman compose --file compose.yaml up --detach

  3. You can view all the containers in the podman desktop. The desktop detects the compose labels and displays the container group or group of containers. for example alt text

  4. If the containers have not started click on the 'play'⏯️ icon against the container.

  5. Alternatively to stop any container click on the 'stop'⏹️ icon

  6. If you wish to delete a container or a group of containers, click the delete icon(🗑) for that container.

  7. Viewing logs or accessing a container terminal.

    Click on the container you want to inspect.

    Four tabs will appear: Summary, Logs, Inspect, and Terminal.

    • Click Logs to view the container’s log output.
    • Click Terminal if you want to open a shell inside the container to interact with it directly.

If using Docker desktop

  1. Open Docker Desktop

    Launch Docker Desktop and wait until it shows:

    Docker Desktop — Running

  2. Open the Containers view

    In the left sidebar, click:

    Containers → [your-repo-name]

    You should see a list of services defined in compose.yaml.

  3. Start all services

Next to the project name, click:

👉 ▶ Start

Docker Desktop will:

  • pull the container images (first time only)
  • start all services listed in compose.yaml
  • show green “Running” indicators
  1. Check that everything is running

Each service should display:

  • a green dot
  • a Running status

You can click any container to view logs, ports, and details.

alt text

  1. Stop all services

To stop everything safely, click:

👉 ⏹ Stop

  1. Restart if needed

You can restart the entire stack by clicking:

👉 ⟳ Restart

💡 Optional: Command Line (for advanced users)

🚀 Launch services

If you prefer using a terminal:

Launch all services :

docker compose up -d

View services status :

docker compose ps

You should see something like that : alt text

Stop services :

docker compose down
🛑 Troubleshooting docker
View logs
docker compose logs -f

This will display the logs of all the containers and the flag -f will keep streaming the output as logs appear

Restart everything
docker compose down
docker compose up -d
Check container status
docker compose ps

Accessing Services

Once started, services are accessible at (considering the port configured in .env file, 8080 in .env.demo provided):

Using Decoder

To be completed....

Using Argo Netcdf File Checker

The file checker endpoint will then be available on http://localhost:8080/argo-toolbox/api/file-checker/check-files (POST method).

The DAC for the files needs to be specified as a parameter and the files to check need to be included in the body of a multipart/form-data type request, e.g.

For example, post a file to http://localhost:8080/argo-toolbox/api/file-checker/check-files?dac=coriolis.

Example files can be found https://github.com/OneArgo/ArgoFormatChecker/tree/main/demo/inputs

curl -X 'POST' \
  'http://localhost:8080/argo-toolbox/api/file-checker/check-files?dac=coriolis' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=@2903996_meta.nc'

🧪 Using JupyterLab

JupyterLab gives you an interactive Python workspace.

The following assumes that the services (file checker, decoder) required for your various notebooks are started.

Open JupyterLab

Navigate to: http://localhost:8080/argo-toolbox/jupyterlab

In the case it asks you a password, you will need to consult the juypyterLab container's logs :

  • go to Docker Desktop, containers and click on the Jupyterlab.

or

  • use the following command :
docker compose logs -f jupyterlab

In the first lines of logs when the container started, you should see a link of the jupyterlab's path along with a token. Use this link to connect to Jupyterlab. Example (be aware that the token change at each run) :

alt text

Then It should open automatically in your browser :

alt text

📂 Example Notebooks

The project includes in examples/notebooks notebooks demonstrating:

  • Working with Git LFS data
  • Decoding source files
  • Validating Argo NetCDF files

🔄 Pull large Git LFS data

git lfs install
git lfs pull

📦 Installing extra Python packages

Inside JupyterLab:

  1. Open a Terminal
  2. Run:
pip install <package-name>

Packages are installed inside the container, not on your Windows system.

🌐 Accessing the API

📄 Endpoints

Open: http://localhost:8080

Available routes will be displayed in JSON format.

alt text

You can test endpoints directly in the browser.

💻 API Usage Examples

🐍 Python

import requests
print(requests.get("http://localhost:8080/<endpoint>").json())

📘 R

library(httr)
content(GET("http://localhost:8080/<endpoint>"))

🟡 MATLAB

response = webread("http://localhost:8080/<endpoint>")

🔵 Julia

using HTTP, JSON
JSON.parse(String(HTTP.get("http://localhost:8080/<endpoint>").body))

🐚 curl (Bash / Zsh)

curl http://localhost:8080/<endpoint>

PowerShell

Invoke-WebRequest -Uri "http://localhost:8080/<endpoint>" |
    Select-Object -ExpandProperty Content

🐞 Reporting Issues

When reporting an issue, please include:

  • Your Windows version
  • Docker Desktop version
  • Steps to reproduce
  • Logs or error messages

Submit issues here:

👉 https://github.com/amrit-eu/Argo-Toolbox/issues

🎉 You’re Ready

You now have a fully functional local environment running:

  • The Toolbox API
  • JupyterLab
  • Example notebooks
  • Multiple access methods

Perfect for “PI on a Laptop” workflows and offline analysis.

About

Home of the Argo Community Toolbox

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages