Skip to main content

Quickstart

This guide will get you up and running with a local instance of the EPOS Platform in just a few minutes. By the end, you'll have a fully functional data catalogue populated with example metadata.

Prerequisites​

Before you begin, make sure you have the following installed and running:

  • Docker: The EPOS Platform runs in containers, so you'll need Docker. Learn how to install Docker.
  • System Requirements: At least 4GB of RAM, 2 CPU cores, and 10GB of free storage.
  • A command-line terminal: The installation is done via the command line.

1. Install the EPOS CLI​

First, you need to install the epos-opensource command-line interface (CLI). This tool will handle the deployment and management of your platform. Choose the tab for your operating system below.

You can install the CLI with a single command in your terminal:

curl -fsSL https://raw.githubusercontent.com/EPOS-ERIC/epos-opensource/main/install.sh | bash

To make sure it's installed correctly, open a new terminal and run:

epos-opensource --version

You should see an output like epos-opensource version v2.0.0 (the exact version number may vary).

For more detailed installation instructions, including how to build from source, see the CLI Tool documentation.

Updating the CLI​

To keep your CLI up to date, you can use the update command. It is the recommended way to get the latest version.

epos-opensource update
warning

When upgrading across major versions (for example, from v1.x to v2.x), read the release notes carefully. v2.0.0 introduces breaking changes in local state handling.

2. Deploy the Platform​

Now, with Docker running, you can deploy the entire EPOS Platform with a single command. Choose a name for your platform instance (e.g., my-epos-platform).

Launch the interactive TUI:

epos-opensource

TUI Home

Click on the Create New Environment in the Docker Environments section.

Deploy New Environment

Enter your environment name (e.g., my-epos-platform) and confirm to start the deployment.

The TUI will show progress as Docker images are downloaded and services start.

TUI Deploy Progress

3. Populate with Example Data​

To see your platform in action, you can populate it with example metadata we provide. This will create a few entries in your data catalogue.

Navigate to a deployed environment details by clicking on it

TUI Env Details

Here you can perform different actions on a deployed environment and see its options/status. As you can see in the Ingested Files section there is nothing, let's add data to our environment. Press on the Populate button

Populate with TUI

Here you can specify the paths to directories or files to ingest. You can also populate an environment with pre-provided example data by checking the Populate Examples checkbox and clicking Populate.

info

After you populate the platform, new data may take a short time to appear in the catalogue. This is expected: the platform refreshes its data in the background every so often, so waiting a little is usually enough.

If you do not want to wait, you can restart the resources-service container:

docker restart my-epos-platform-resources-service

Remember to replace my-epos-platform with the name you used when deploying the environment.

If the data still does not appear after a short wait or a restart, please open an issue on GitHub.

4. Explore Your New Platform​

Congratulations, your EPOS Platform is live!

Open your web browser and go to the EPOS Platform GUI URL shown after deployment (or click Open in the TUI). The default URL is http://localhost:32000/, but use the printed URL if your machine required different ports.

The EPOS Platform

You should see the main interface for browsing and searching for geospatial services. The example metadata will appear on the top-left side of the interface.

You can also explore the API Documentation at http://localhost:33000/api/v1/ui (or the API URL printed by the CLI).

Next Steps​

Now that you have a running instance, you can: