Getting started#

Setting up the SkyTracker application requires several steps to ensure external APIs and the database server function correctly. On this page, the required steps are detailed:

Install the SkyTracker package (Installation)
Set up ClickHouse database server (ClickHouse server)
Get OpenSky Network API credentials (OpenSky Network API credentials)
Set up environment variables (Environment variables)

Installation#

To install SkyTracker, first clone the repository:

git clone https://github.com/JasperJeuken/SkyTracker

Next, use uv to install the package:

uv sync

Alternatively, use pip to install:

pip install -e .

ClickHouse server#

SkyTracker uses ClickHouse to store data in a database. There are several options for setting this up:

ClickHouse cloud
Local Docker container

After setting up a cloud or local server, create a .env file in the root of the repository by following the instructions in Environment variables.

ClickHouse cloud#

Use the following steps to set up a ClickHouse cloud database which hosts the server in the cloud. Note that after a 30-day trial period, a plan needs to be selected (see ClickHouse pricing).

Go to the ClickHouse website and click Get started.
Sign in or create an account.
Configure a service (select a provider and region).
In the ClickHouse console, click Connect, and copy the username and password (reset it if you did not make one yet), as well as the host URL.
Follow the instructions under Environment variables to set up the environment variables.

Local Docker container#

Use the following steps to set up a Docker container which hosts this server locally:

Pull latest ClickHouse server container

docker pull clickhouse/clickhouse-server

Create an XML file to specify user priviliges. Any filename is acceptable. The path to the file is needed later. Add the following file content:

<yandex>
    <users>
        <default>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
            <show_named_collections>1</show_named_collections>
            <show_named_collections_secrets>1</show_named_collections>
        </default>
    </users>
</yandex>

Run a new server with specific settings, including the XML file created in step 2. The name of the server can be adjusted. Use the following command:

docker run -d --name my-server-name --ulimit nofile=262144:262144 -v "$PWD/path/to/created.xml:/etc/clickhouse-server/users.d/default-user-access.xml" -v "clickhouse_data:/var/lib/clickhouse/" -v "clickhouse_logs:/var/log/clickhouse-server" -p 8123:8123 -p 9000:9000 clickhouse/clickhouse-server

Enter the native client from the console (use the same server name as specified in step 3):
docker exec -it my-server-name clickhouse-client

Create a new user (select username and password):

CREATE USER myusername IDENTIFIED BY 'mypassword';

Grant the new user access to all commands:
GRANT ALL ON *.* TO myusername;
Exit the native client:
quit
Follow the instructions under Environment variables to set up the environment variables.

OpenSky Network API credentials#

The SkyTracker application pulls data from the OpenSky Network API. This requires API credentials, which can be obtained from the website:

Create an account on the OpenSky Network website.
On your account page, copy the client ID and client secret.
Follow the instructions under Environment variables to set up the environment variables.

Please note that the API comes with several limitations, as outlined on the page REST API. Notably, users receive a set amount of credits, which are spent based on the performed requests (see API credit usage). For a regular user, if requesting the states of all aircraft, this amounts to roughly one request every minute and a half.

Environment variables#

The SkyTracker application uses environment variables to change settings within the program. Use these steps to set them up correctly:

Create the file .env in the root directory.

Add the following content to the file:

CLICKHOUSE_HOST=hostname        # localhost or URL to cloud server
CLICKHOUSE_PORT=0               # server port (0 = use default)
CLICKHOUSE_USER=myusername      # name of user on server
CLICKHOUSE_PASSWORD=mypassword  # password of user on server
CLICKHOUSE_SECURE=False         # typically False for local server, True for cloud server
CLICKHOUSE_DATABASE=default     # name of database to use on server (typically "default")

OPENSKY_CLIENT_ID=client-id          # OpenSky Network API client ID
OPENSKY_CLIENT_SECRET=client-secret  # OpenSky Network API client secret

APP_NAME=SkyTracker      # Name of application in FastAPI
ENVIRONMENT=development  # FastAPI environment mode (development, staging, or production)
DEBUG=True               # Whether to start in debug mode

Usage#

Run the API server (using uv):

uv run fastapi dev skytracker/main.py

Alternatively, run without uv:

fastapi dev skytracker/main.py

Table of Contents