Portainer Templates logo

Portainer Templates

AsoBeast AsoBeast

Stack

AnalyticsMonitoring

App Store Optimization for iOS and Android apps: tracks your App Store and Google Play keyword rankings every day, along with competitors, reviews and a list of fixes ranked by impact. Source: https://github.com/AsoBeast/asobeast

Source details

Stars: 151
Forks: 26
Language: TypeScript
License: AGPL-3.0
Updated: 18 hours ago
Website: asobeast.com/

Configuration

Type
Compose
Platform
linux
Env vars
POSTGRES_PASSWORD=''AUTH_SECRET=''ASOBEAST_PORT=3001WEB_PUBLIC_URL=''TRUST_PROXY=0
Restart
unless-stopped
Source

Notes

Set a database password and a session secret before you deploy. openssl rand -hex 32 makes both, and the stack won't start without them. AsoBeast listens on the host port you choose, 3001 unless you change it. Its session cookie is always secure, so sign in over https: put a reverse proxy with a certificate in front and set the address and proxy count above. Chrome and Firefox also accept it on http://localhost:3001 (or your port), which works from another machine through ssh -N -L 3001:localhost:3001 you@<your-host>, with the second 3001 replaced by your host port when you changed it. The first account created at /register becomes the owner and registration closes after that, so create it right away. Any other API setting, such as SMTP or OpenAI, goes in as an extra environment variable on the stack. Data lives in the <stack name>_pgdata and <stack name>_redisdata volumes, and the stack needs about 2.5 GB of memory. To update, back up, then pull and redeploy the stack: the compose file on main pins the current release. Docs: docs.asobeast.com/install/published-images

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

  1. Ensure both Docker and Portainer are installed, and up-to-date
  2. Log into your Portainer web UI
  3. Under Settings → App Templates, paste the below URL
  4. Head to Home → App Templates, and the list of apps will show up
  5. Select AsoBeast, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me demo

More install options in our documentation, or see AsoBeast/asobeast for app-specific guidance.

AsoBeast logo

AsoBeast

AsoBeast is an open-source App Store Optimization (ASO) tool and keyword rank tracker for the Apple App Store and Google Play.

See where your app ranks for every tracked keyword each day, and what to change next.

Use the hosted service at asobeast.com, 7 days free on a card, or self-host it free with Docker under AGPL-3.0. Both run the same code.

<a href="https://app.asobeast.com/register?utm_source=github&utm_medium=readme&utm_campaign=hero"><img alt="Start a free 7-day AsoBeast trial" src="https://img.shields.io/badge/Start_free_7--day_trial-a8520a?style=for-the-badge" /></a>
<a href="#quick-start"><img alt="Self-host with Docker" src="https://img.shields.io/badge/Self--host_with_Docker-57606a?style=for-the-badge" /></a>

<a href="https://github.com/AsoBeast/asobeast/blob/HEAD/LICENSE"><img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" /></a>
<a href="https://github.com/AsoBeast/asobeast/releases"><img alt="Latest release" src="https://img.shields.io/github/v/release/AsoBeast/asobeast" /></a>
<a href="https://github.com/AsoBeast/asobeast/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/AsoBeast/asobeast?style=flat" /></a>

<a href="https://docs.asobeast.com">Docs</a> ·
<a href="https://docs.asobeast.com/mcp/introduction">MCP server</a> ·
<a href="https://docs.asobeast.com/api-reference/introduction">API</a> ·
<a href="https://github.com/AsoBeast/asobeast/releases">Releases</a> ·
<a href="https://docs.asobeast.com/support">Support</a>


AsoBeast dashboard: App Store and Google Play search visibility over 90 days, keyword movers and the next ASO actions

What is AsoBeast?

AsoBeast is a self-hostable ASO tool for App Store and Google Play keyword research and daily rank tracking. It imports a listing, tracks its keyword rankings every day, watches competitors, reviews and listing changes, and turns that history into a prioritized list of ASO work. It is an open-source alternative to AppTweak and AppFollow for keyword research and rank tracking, built for indie developers, small studios and agencies with a portfolio measured in apps rather than hundreds.
A self-hosted AsoBeast sends every store request as an ordinary public search or page request from your own server. You need no ASO vendor account or API key, your keyword list stays in your own database, and there is no telemetry.

Quick start

Start a free 7-day trial at asobeast.com if you would rather not run a server. To self-host, deploy on Railway in one click, or run Docker Compose on any machine with about 2.5 GB of memory and 5 GB of disk.
Deploy on Railway
The Railway template runs the published images with PostgreSQL and Redis and generates every secret.
To run the published images with Docker Compose instead:
curl -fsSLO https://raw.githubusercontent.com/AsoBeast/asobeast/main/docker-compose.pull.yml
printf 'POSTGRES_PASSWORD=%s\nAUTH_SECRET=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
chmod 600 .env
docker compose -f docker-compose.pull.yml up -d --wait

Open http://localhost:3001, create the owner account (registration then closes) and import a store URL. AsoBeast picks keywords from the listing and runs their first rank checks right away.
!NOTE Safari drops the session cookie on plain HTTP, so use Chrome or Firefox for a local evaluation or put the instance behind HTTPS. See troubleshooting.

Build from source instead
git clone https://github.com/AsoBeast/asobeast.git
cd asobeast
printf 'POSTGRES_PASSWORD=%s\nAUTH_SECRET=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
chmod 600 .env
docker compose up --build -d --wait


A default AsoBeast installation needs only POSTGRES_PASSWORD and AUTH_SECRET. The configuration reference lists every other option, and run a published release covers image tags and pinning.
If AsoBeast works for you, a star on this repository helps other app developers find it.

Connect an AI agent over MCP

Create a personal API token on the Integrations page, then add your instance to Claude Code:
claude mcp add --transport http asobeast https://your-host/api/backend/mcp --header "Authorization: Bearer asob_…"

Ask the agent which keywords dropped this week, which competitor entered the top 10 or which action the Action Center ranks first. Set up the MCP server covers Claude Desktop, Cursor, VS Code, Gemini CLI, Windsurf and the local stdio server, and MCP recipes has prompts to start from.

Features

AsoBeast keyword rank tracker: daily positions, 7-day trends, popularity, difficulty and the top-ranking apps per keyword
  • Import any App Store or Google Play URL once and track its keywords daily in as many countries as you need. Setup suggests markets from the languages your listing ships.
  • Rank checks read as deep as each store lists, up to 200: the App Store usually returns 140 to 200 results and Google Play about 30. One search per keyword covers your app and every competitor.
  • Research any keyword before you track it: the keyword inspector shows popularity, difficulty, the store's autocomplete and the top 50 apps in any country, and keyword discovery finds the searches your app already ranks for.
  • AsoBeast scores every keyword for popularity, difficulty and opportunity, and each score shows its source, calculation version, capture date and confidence. Popularity estimates a keyword's search demand, and difficulty estimates how hard its current top results are to displace. The scoring method is published and versioned.
  • Competitors come from live search results, with the keyword gaps where each one outranks you, and you can follow top charts by country and category.
  • The metadata workbench lints each indexed field against its store limit and holds one private iOS keyword field per localization.
  • Link the App Store and Google Play listings of one product into a portfolio group, and send its weekly digest to an alert channel.
  • Every metadata change, yours or a competitor's, lands in the changes feed. Your own changes show what they did to positions and visibility after 7, 14 and 28 days.
  • Reviews sync with their ratings, and repeated language in negative reviews becomes keyword ideas. You can draft a reply with AI and, with the store console connected, post it once you approve it.
  • The Action Center runs seventeen deterministic rules over your history and ranks what to do next, each action with the numbers behind it. AI can summarize an action but never adds or reorders one. The audit scores the listing itself.
  • Connect an App Store Connect key or a Google Play service account to read the store's own reports: impressions, page views, Get taps and conversion on the App Store, and installs per search term on Google Play.
  • Alerts for rank drops, first rankings, metadata changes, chart moves, rating drops and review spikes go out by email, webhook, Slack, Discord, Microsoft Teams, Telegram or Google Chat.
  • The MCP server gives Claude, Cursor, VS Code and other clients 42 read tools and 8 opt-in write tools, and the HTTP API is documented with OpenAPI.

What's new in AsoBeast 2

AsoBeast 2 redesigns every screen. The dashboard and each app's overview open with what moved and what to do next, and the keywords page shows a trend line and the top apps for every keyword. AsoBeast 2 also adds the keyword inspector, featuring readiness in the audit and a ratings goal, and the changes feed now records in-app events and featuring.
Upgrading from AsoBeast 1.x needs no script or agent changes, because nothing in the HTTP API or the MCP tools was removed, renamed or narrowed, and the API migrates the database on boot. If you pin the image tag 1, change it to 2, because a major tag never moves to the next major. See upgrade and roll back.

How AsoBeast compares

AsoBeast (self-hosted)Subscription ASO platforms
Where store requests runYour machineTheir infrastructure
Who sees your keyword listYouThe vendor
Cost modelYour hosting billPer seat, per app or per keyword
Keyword historyYours, retained on your termsUsually ends with the subscription
Score methodologyPublished, versioned, inspectableUsually proprietary
Extending itFork it, it is AGPL-3.0File a feature request

AsoBeast has no open core: the hosted service at asobeast.com runs the same code with every feature, so you can start on the 7-day free trial without running a server.

Frequently asked questions

Is AsoBeast free and open source?

AsoBeast is free and open source under AGPL-3.0. The hosted service at asobeast.com is paid, from \$10 a month, after a 7-day free trial on a card. Cancel before day 7 and nothing is charged. See pricing. If you offer a modified version as a network service, the AGPL asks you to share that modified source with its users.

What is App Store Optimization (ASO)?

App Store Optimization (ASO) is the practice of improving how an app listing ranks and converts in App Store and Google Play search and charts.

How do I track App Store and Google Play keyword rankings?

Import the app's store URL into AsoBeast. It picks keywords from the listing, runs their first rank checks right away, then checks every tracked keyword once a day in each country you add. See track keywords.

Is AsoBeast an alternative to AppTweak or AppFollow?

For keyword research and daily rank tracking, yes. AsoBeast tracks App Store and Google Play rankings per country, scores keywords with a published method and imports keyword lists exported from AppFollow, Astro and Sonar. AsoBeast does not replace a large commercial ASO suite: it has no download or revenue estimates, and it checks the stores at a modest rate.

Does AsoBeast need an App Store Connect or Google Play Console account?

No. AsoBeast reads public store data, so you can track any app, including your competitors. Connecting a console is optional and adds the store's own impressions, page views and conversion for your apps, and installs per search term on Google Play. The key is sealed at rest. See the store funnel.

How often does AsoBeast check keyword rankings?

AsoBeast checks every tracked keyword once a day, by default at 03:00 UTC, on a schedule you can change. A position of null means the app was checked and not found within the depth checked, up to 200. See positions.

Which app stores does AsoBeast support?

AsoBeast supports the Apple App Store and Google Play. Apple indexes the title, the subtitle and a private 100-character keyword field. Google Play indexes the title, an 80-character short description and the long description. See stores.

Can I track keywords in more than one country?

Yes. An app is imported once and each tracked keyword carries its own country, so one listing can track many markets. Each market adds daily store requests, and setup shows what a market costs before you add it. See countries and markets.

Can I connect AsoBeast to Claude or another AI agent?

Yes. Every AsoBeast instance serves a Model Context Protocol (MCP) endpoint. Each connection needs a personal API token and only reads by default. The tools that change data are listed only to a token you give the write scope. See MCP tools.

Can I import keywords from another ASO tool?

Yes. The keyword import reads CSV exports from Astro, AppFollow and Sonar by their column headers, or any file with a keyword column. Positions and scores in the file are not imported, because AsoBeast measures them itself, so rank history starts on the day you import. See files from other tools.

Does AsoBeast send my data anywhere?

By default, a self-hosted AsoBeast sends only store requests from your server: public searches and listing pages, from your own address or through a proxy you configure. Everything else is off until you set it up: alerts, email, OpenAI assistance, Apple Ads popularity, the store status check and a connected App Store Connect or Google Play Console account. There is no telemetry. See what leaves your deployment.

Limitations

  • AsoBeast scores are store-specific estimates built from public evidence. They are not comparable across stores and do not replace first-party download data.
  • AsoBeast reads public store endpoints, and a store can change one without notice. When a parser breaks, its job fails and is retried with backoff. Request handling is not affected.
  • Store rate limits, not hardware, cap how many keyword markets one instance can track. See capacity and limits.
  • On a self-hosted instance, backups, TLS, monitoring and upgrades are yours to run.

Documentation

Quickstart · Self-host with Docker Compose · How AsoBeast works · Feature guides · Backups, restore and upgrades · API reference · MCP tools · Support
For language models, the whole site is available as llms.txt and llms-full.txt.

Contributing

Pull requests are welcome. Read CONTRIBUTING.md first for the commit conventions, the compatibility promise and how to run the tests. Report bugs in GitHub issues, bring questions and ideas to GitHub Discussions, and send security reports through SECURITY.md, never a public issue.
AsoBeast is a TypeScript monorepo: NestJS, Prisma, PostgreSQL, BullMQ and Redis on the API side, Next.js and Tailwind on the web side. Local development and how AsoBeast works explain the setup and the architecture.
Contributors to AsoBeast

License

AsoBeast is licensed under AGPL-3.0-only. The license grants no trademark rights. TRADEMARKS.md explains how the AsoBeast name and logo may be used. AppTweak, AppFollow, Astro and Sonar are trademarks of their owners and are named only to describe compatibility and alternatives.

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

  • In Portainer, go to Containers, click the container, then Logs. Or run docker logs <container>
  • Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

  • Check the logs right after a restart, the last few lines before it died are the useful ones.
  • Get the exit code with docker inspect <container> --format '{{.State.ExitCode}}'
  • Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Required settings are blank

POSTGRES_PASSWORD, AUTH_SECRET, WEB_PUBLIC_URL have no default value, and asobeast may crash or misbehave if left empty.

  • Fill them in on the deploy screen before hitting deploy.

Stack won't deploy

Compose stacks fail fast on small mistakes, and Portainer shows the reason just above the editor.

  • YAML only accepts spaces for indentation, a single tab breaks the whole file.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

A Compose stack

AsoBeast is a Compose stack, a set of containers defined in one file and brought up together by Portainer, then started and stopped as a single app.

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. AsoBeast takes 5 of them, and 3 need a value before it'll start properly:

  • POSTGRES_PASSWORD, needs a value. Generate one with: openssl rand -hex 32. It goes into the database URL unencoded, so characters such as # @ / : % break the connection. Keep it the same on every redeploy, or the API can't reach its database.
  • AUTH_SECRET, needs a value. Signs sign-in sessions. Generate one with: openssl rand -hex 32. The API refuses to start when it is shorter than 32 characters.
  • ASOBEAST_PORT, defaults to 3001. The port on this machine AsoBeast answers on. Keep 3001 unless another service already uses it. An address you type below must use the same port.
  • WEB_PUBLIC_URL, needs a value. Builds the links in alert, confirmation and password reset emails. Leave it empty to use http://localhost on the host port above, or enter your https address when AsoBeast sits behind a reverse proxy.
  • TRUST_PROXY, pick one of 0, 1, 2. The number of proxies you control between the internet and AsoBeast, so rate limits see each visitor's own address.

Restart policy

The restart policy here is unless-stopped, so Docker restarts AsoBeast after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Networking

Nothing custom is set, so AsoBeast sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container asobeast. That's what you'll spot in the containers list and use in commands like docker logs asobeast.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Open source license

AsoBeast is open source, released under the AGPL-3.0 license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set AsoBeast up. Add the template list to Portainer once, then deploying AsoBeast is a click rather than a wall of config.