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
3
Start the stack
--wait returns only after every health check passes.4
Open the dashboard
Go to
http://localhost:3001.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. SetAUTH_ALLOW_REGISTRATION=true only when further sign ups should stay available. The Compose stack already sets AUTH_COOKIE_SECURE=true, which keeps working over http://localhost and behind TLS. Leave it there; only a development API run outside Docker sets it to false. 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.- 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 tous. - Fetches the listing and writes the first metadata snapshot, keeping the raw payload so a later parser fix can reprocess it.
- Extracts keywords from the indexed fields and starts tracking them in the home storefront.
- 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.
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.
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 the platform operator, which is deliberate. See Health checks and monitoring.
What happens on day two?
The daily pipeline starts atCRON_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.
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.
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.