Installation

This page takes you from nothing to a running dashboard with your App Store data in it: create an API key, start OpenConnect with Docker, set a password, and let the first sync run.

What You Need

• Docker with Compose: Docker Desktop on macOS or Windows, or Docker Engine on Linux. Published images run on Intel and ARM, including Apple Silicon and Raspberry Pi.
• An App Store Connect account with access to Users and Access, to create an API key.
• Git, to get the compose file and source.

To run without Docker, you need Node.js 22 or later. See Run Without Docker.

Create an App Store Connect API Key

OpenConnect reads your data with an App Store Connect API Team Key.

1. Sign in to App Store Connect and go to Users and Access > Integrations > App Store Connect API.
2. Create a Team Key. Give it a name, such as "OpenConnect", and choose its access role from the table below.
3. Note the Issuer ID shown above the list of keys, and the new key's Key ID.
4. Download the private key. It's a file named AuthKey_<KEY_ID>.p8. Apple only lets you download it once, so keep it somewhere safe.

Data	Role the key needs
Apps and customer reviews	Any role, such as Customer Support or App Manager
Sales, proceeds, in-app purchases, subscriptions	Sales (or Finance, or Admin)
Impressions and product page views	Admin once, so OpenConnect can ask Apple to start generating analytics reports. A Sales key can download them afterwards.
Ratings and rankings in 175 storefronts	None. These come from Apple's public lookup and top-chart feeds.

A Sales key covers everything except the one-time impressions setup. See Impressions and Product Page Views.

Find Your Vendor Number

Sales and subscription reports also need your Vendor Number. In App Store Connect, open Payments and Financial Reports. The number is at the top left, under your name.

Start OpenConnect

1. Get the code:

   git clone https://github.com/OddOmens/OpenConnect.git
   cd OpenConnect

2. Create your settings file and fill in ASC_KEY_ID, ASC_ISSUER_ID and ASC_VENDOR_NUMBER:

   cp .env.example .env

   ASC_KEY_ID=ABC123DEFG
   ASC_ISSUER_ID=00000000-0000-0000-0000-000000000000
   ASC_VENDOR_NUMBER=80012345

3. Put the private key in the keys folder. It's found there automatically by its file name:

   cp ~/Downloads/AuthKey_ABC123DEFG.p8 keys/

4. Start it:

   docker compose up -d

   This pulls the published images. To build from the source you cloned instead, run docker compose up -d --build.

You can also leave .env empty and enter the key details, including the contents of the .p8 file, in Settings > App Store Connect after you sign in. See Configuration.

TIP

The screenshot studio, app promo cards and API tokens are on the main branch but not yet in a published release (the latest is 1.2.0). To use them now, start OpenConnect with docker compose up -d --build.

Set Your Password

1. Open http://localhost:3000.

2. OpenConnect asks you to choose a password. To prove you own the server, it also asks for a one-time Setup code. Find it in the server log:

   docker logs openconnect

   Look for a line like [auth] No password set yet. Open OpenConnect and enter this setup code: ABCD-EFGH.

3. Enter the setup code, a New password of at least 10 characters, and Confirm password, then click Set password and continue.

To fix the password in .env instead, or to run without one, see Security.

The First Sync

About 30 seconds after OpenConnect starts, it runs its first sync on its own. It backfills your history as far back as Apple allows, which takes a few minutes, and checks your ratings and chart positions in every storefront. Click the Sync button at the top of the dashboard to watch its progress.

After that, sales sync every 6 hours and ratings and rankings once a day. Syncing explains what is downloaded and how to change the schedule.

To check the key without waiting, go to Settings > App Store Connect and click Save & test connection. It shows whether Apps, Reviews and Sales reports work with your key.

Open It From Other Devices

By default, OpenConnect only accepts connections from the computer it runs on (BIND_ADDRESS=127.0.0.1).

• On your home network: set BIND_ADDRESS=0.0.0.0 in .env and run docker compose up -d again. Then open http://<computer's address>:3000.
• Anywhere, privately, over HTTPS: use Tailscale, as described next.

Never expose OpenConnect directly to the internet.

HTTPS With Tailscale

docker-compose.tailscale.yml adds a Tailscale container that serves OpenConnect at https://openconnect.<tailnet>.ts.net on your tailnet. Browsers block some features, such as downloading marketing cards, on plain http:// pages that aren't localhost, so this address is also the way to get those working from other devices.

1. In the Tailscale admin console, under DNS, turn on MagicDNS and HTTPS certificates.

2. Start OpenConnect with both compose files:

   docker compose -f docker-compose.yml -f docker-compose.tailscale.yml up -d

3. On the first start, open the login link Tailscale prints:

   docker logs openconnect-tailscale

To skip the login link, set TS_AUTHKEY in .env. Tailscale's state is kept in ./tailscale, so you only log in once. TS_HOSTNAME changes the name (default openconnect).

Run Without Docker

Requires Node.js 22 or later.

npm install
cp .env.example .env.local   # fill in
npm run dev                  # http://localhost:3000

Data goes to ./data, or the folder set by DATA_DIR. The setup code is printed in the terminal. For the screenshot studio, also see Screenshot Studio.