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:3001. The dashboard leads with four tiles for keywords in the top 10, keyword movement, open actions and changes this week, then lists your apps. See Read the dashboard.

​
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. The Compose stack already sets AUTH_COOKIE_SECURE=true, which Chrome and Firefox keep over http://localhost and every browser keeps behind TLS. Safari needs TLS, so use another browser for a local evaluation or see Signing in returns to the sign in form. Leave it at true; only a development API run outside Docker sets it to false. See Authentication and accounts.

​
Import your first app

Type your app’s name into the import dialog and pick it from the results, or paste its App Store or Google Play URL. 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.
  4. Schedules its own first pass: a rank check for every tracked keyword, a score for every tracked keyword and one action generation run for your workspace.
On a fresh instance with an empty queue the first positions and scores arrive within minutes on the App Store and within tens of minutes on Google Play, because the whole first pass is queued at import rather than waiting for the next scheduled run. See Import an app.

​
The panel that says what is still running

Until every stage has landed, the app overview page shows a panel naming what is still being collected and, where the schedule can be read, when the rest arrives. It stops rendering and stops polling on its own once collection is done, so there is nothing to dismiss. It is a status report rather than a notification. Two horizons are worth knowing before you read it.
  • Positions and scores arrive as the queue drains, in minutes rather than days, and the daily and weekly runs catch anything that failed on the first attempt.
  • The trend rules need a week. Rules that compare a before against an after cannot fire until several days of daily captures exist, so the action queue grows over the first week rather than arriving full. The panel counts those days so a thin queue reads as young rather than broken.
The iOS keyword field holds 100 characters, never appears on the public store page and cannot be collected. Type it by hand on the metadata page, once for each localization you filled, so coverage and audit checks can see it. See Edit the iOS keyword field.

​
Complete the guided setup

The first import opens a guided setup with three steps, in this order, each one done inside its own card.
  1. Pick competitors. Track at least one. The apps ranking in your keyword results and the apps the store calls similar are suggested with a checkbox each and added together, and any other app can be added by name or from its store URL. See Suggested competitors.
  2. Track keywords. Track at least ten in your home storefront. Tick phrases from your listing or from the store autocomplete and track them in one click.
  3. Add countries. The storefronts that read a language your listing ships are suggested with their daily request cost, and any other country can be chosen from the list. See How do you add a market?
A step can be skipped with one click and undone later. Completing the setup opens the app overview, where the first run panel lists the first positions as they arrive. Progress is kept on your account, so you can continue on another device and a teammate sees the same steps. Each imported app has a setup of its own, so two apps can be set up at once, and the dashboard names the one you touched last.

​
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 the platform operator, 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, category ranks and the top charts your apps sit in or you follow, syncs reviews, generates action items and then flushes batched alerts. The import already collected the first positions, scores and action items, so the daily run is what keeps them current rather than what produces them. What it adds on day two is the second capture, which is the first point a chart can draw a line between. 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 the platform operator a daily request budget card, and GET /jobs/budget returns the same estimate.

​
Next steps

Track keywords

Add keywords, import a list and add markets.

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 October 15, 2026