Skip to main content
By the end of this page you have asobeast running on your own machine, an owner account, and one app importing its metadata and tracking its first keywords.
The only prerequisite is Docker with the Compose plugin. See System requirements for memory, disk and network detail.

​
Install and start asobeast

1

Clone the repository

2

Generate the two required secrets

Compose refuses to start when either value is missing or empty.
3

Start the stack

The first build takes a few minutes. --wait returns only after every health check passes.
4

Open the dashboard

Go to http://localhost:3000.

​
Create the owner account

A fresh installation redirects to registration. The first account you create becomes the owner, and registration closes automatically once it exists. Set AUTH_ALLOW_REGISTRATION=true only when further sign ups should stay available. Behind TLS on any hosted deployment, also set AUTH_COOKIE_SECURE=true. See Authentication and accounts.

​
Import your first app

Paste an App Store or Google Play URL into the import dialog. asobeast then does the following, in order.
  1. Parses the store and the home storefront from the URL. A bare iTunes id, or a URL with no country segment, falls back to DEFAULT_COUNTRY, which defaults to us.
  2. Fetches the listing and writes the first metadata snapshot, keeping the raw payload so a later parser fix can reprocess it.
  3. Extracts keywords from the indexed fields and starts tracking them in the home storefront.
Positions are not instant. The first ranking check happens on the next daily pipeline run, so the app detail page shows metadata and tracked keywords immediately and positions from the following morning. See Import an app.
The iOS keyword field holds 100 characters, never appears on the public store page and cannot be collected. Paste it by hand in the metadata workbench so coverage and audit checks can see it.

​
Complete the guided setup

After the first import the dashboard offers a resumable checklist that walks through the decisions worth making early: which markets to track, which competitors to watch, which keywords to add, how much daily request capacity you have, and whether to send alerts anywhere. The checklist is stored in your browser, so you can leave it and come back.

​
Check that collection is running

A healthy queue has no jobs in the failed list and shows the daily pipeline as scheduled rather than running around the clock. /admin/queues answers 404 to anyone who is not a signed in owner, which is deliberate. See Health checks and monitoring.

​
What happens on day two?

The daily pipeline starts at CRON_DAILY, which defaults to 0 3 * * *, meaning 03:00 UTC. It checks every tracked keyword in every tracked market, captures SERP snapshots and category ranks, syncs reviews, generates action items and then flushes batched alerts. So the first positions, the first movers and the first action items all appear the morning after the import. An empty ranking chart on the day you install is expected. See The daily pipeline and rate limits.
Daily request volume scales with tracked keywords multiplied by tracked markets, against a fixed budget set by SCRAPE_ITUNES_RPM and SCRAPE_GPLAY_RPM. The settings page shows a daily request budget card, and GET /jobs/budget returns the same estimate.

​
Next steps

Track keywords

Add keywords, add markets and paste the iOS keyword field.

Work the Action Center

Turn the collected history into a prioritized queue of work.

Configuration reference

Every environment variable with its default and its effect.

Send alerts

Signed webhooks or SMTP email for rank, review and action events.
Last modified on July 31, 2026