Install the Shopify app.

Who this guide is for

Rilea SEO for Shopify isn’t installed from the Shopify App Store. It’s a self-hosted app: you download the source, run it on a server you control, and install it on your store, or your clients’ stores, as a custom app. That means no monthly subscription and no third party holding your store’s SEO data, but it does mean someone needs to be comfortable with a terminal, Node.js and a hosting platform.

If you’re a developer, an agency or a technical store owner, this guide takes you from the download to a working installation. If you’re not technical, share this page with whoever looks after your store’s code.

How the app is built

Knowing the architecture makes setup and troubleshooting easier.

• An embedded admin app. Rilea SEO runs inside your Shopify admin, built on Shopify’s official React Router app template with Polaris web components and App Bridge. It feels like part of Shopify, not a separate website.
• A theme app extension. Everything Rilea SEO adds to your storefront, such as verification tags, JSON-LD schema, social tags and robots tags, comes from a theme app extension called rilea-theme. There’s an app embed that prints into the page head, and app blocks for breadcrumbs, FAQs, a table of contents and HowTo steps. The app never edits your theme files, and it doesn’t use ScriptTags, which Shopify is retiring.
• Native SEO fields. SEO titles, meta descriptions, URL handles and image alt text are saved to Shopify’s own fields. If you uninstall the app, your SEO stays in place.
• A database and a worker. PostgreSQL stores settings, analysis scores and history. Redis powers a background worker that handles catalog scans, bulk edits, CSV import and export, and scheduled syncs.

What you need

• A Shopify Partner or Dev Dashboard account, and a development store for testing.
• Node.js 22.12 or later, and the Shopify CLI, which you can install with npm i -g @shopify/cli.
• Docker for running PostgreSQL and Redis locally.
• A production host that serves the app over HTTPS. The download includes a configuration for Fly.io, with Fly Postgres and Upstash Redis, but any Node.js host with PostgreSQL and Redis will work.

Running it locally

Start on your own machine with a development store. It’s the quickest way to see the app working and to check everything before you deploy.

1. Unzip the download and open the folder in a terminal.
2. Install dependencies with npm install.
3. Create your environment file. Copy .env.example to .env. The database and Redis defaults already match the included Docker setup.
4. Start the database and Redis with docker compose up -d. This runs PostgreSQL 16 and Redis 7.
5. Create the tables with npx prisma migrate deploy.
6. Link your app with npm run config:link. The CLI asks you to choose or create an app in your Dev Dashboard and fills in its client ID.
7. Start the app with npm run dev. The Shopify CLI opens a tunnel, installs the app on your development store and serves the theme extension.
8. Start the worker in a second terminal with npm run worker. Without it, jobs run inside the main process and the scheduled content sync for pages and blog posts doesn’t run.
9. Open the app. Press p in the first terminal to open it in your development store.

Turning on the theme embed

The first time you open the dashboard, it shows a banner saying Rilea SEO isn’t active on your live theme. Shopify requires merchants to switch app embeds on themselves, so this step is always manual:

1. Click Turn on Rilea in theme editor. The theme editor opens with the Rilea SEO embed selected.
2. Click Save in the theme editor.
3. Go back to the app and click Check again. The banner changes to say Rilea SEO is active.

If you later publish a different theme, the app notices and checks again, and the dashboard warns you if the embed needs switching on for the new theme.

Environment variables

These are the settings the app reads from its environment:

• SHOPIFY_API_KEY and SHOPIFY_API_SECRET. Required. The Shopify CLI sets them during local development; set them as secrets in production.
• SHOPIFY_APP_URL. Required. The public HTTPS address of your app.
• SCOPES. Required. Must match the scopes in shopify.app.toml.
• DATABASE_URL. Required. Your PostgreSQL connection string.
• REDIS_URL. Required in production for scans and bulk jobs. Use a rediss:// address for Upstash.
• APP_DISTRIBUTION. Set to custom while you install on your own and client stores.
• SHOPIFY_RILEA_THEME_ID. Optional. The theme extension’s ID, which makes embed detection exact.
• WORKER_CONCURRENCY. Optional. How many jobs the worker runs at once. The default is 4.

Deploying to production

The included configuration targets Fly.io. The steps are similar on other hosts.

1. Create the app. Edit the app name and region in fly.toml, then run fly launch --no-deploy.
2. Add a database. Run fly postgres create, then fly postgres attach with your database app’s name. This sets DATABASE_URL for you.
3. Add Redis. Create a Redis database, for example on Upstash, and copy its connection URL.
4. Set your secrets. Use fly secrets set to add SHOPIFY_API_KEY, SHOPIFY_API_SECRET, SHOPIFY_APP_URL, SCOPES and REDIS_URL.
5. Deploy with fly deploy. Database migrations run automatically before the new version starts, and both the web app and the worker start.
6. Update the app configuration. In shopify.app.toml, set application_url and redirect_urls to your production address.
7. Push the configuration to Shopify with npm run deploy. This sends the app settings, webhooks, app proxy and theme extension to Shopify.

The app has a health check at /healthz that confirms the database is reachable, which Fly.io uses to know the app is running.

Installing on a store

1. Choose custom distribution. In the Dev Dashboard, open your app’s distribution settings, choose custom distribution and enter the store’s myshopify.com domain.
2. Open the install link Shopify generates and approve the app on the store.
3. Turn on the theme embed as described above.
4. Fill in the settings. In the app’s Settings, add your site name, title separator, verification codes, social profiles, default share image and organization details.

For agencies, repeat the custom distribution step for each client store. One deployment can serve many stores.

The permissions it asks for

Every access scope has a reason, and the app asks for nothing it doesn’t use.

• Products, content and online store pages, read and write. To read and save SEO titles, descriptions, handles, noindex settings and image alt text for products, collections, pages, blog posts and blogs.
• Navigation, read and write. To read menus for the orphaned content report. Shopify also requires write access to create URL redirects.
• Themes, read only. To check whether the embed is on, and to find duplicate schema or canonical tags in your theme.
• Files, read and write. For the image picker used for social images and logos.
• Metaobjects and their definitions. For locations, FAQs and HowTo content that your theme can display.
• Translations, locales and markets, read only. To show translated SEO fields and use the right currency in product schema for each market.
• App proxy. For storefront features served under /apps/rilea/.

It doesn’t ask for customer or order data, inventory, or permission to write theme files.

Your first hour with the app

Once the embed is on, these steps get the most value quickly:

1. Check your settings. General, Social and Schema are the most important on day one.
2. Set templates. In Titles & Templates, set title and description templates for products, collections, pages and blog posts.
3. Apply templates to empty fields. In the Bulk Editor, apply templates to content without a custom title or description. You’ll see a preview first, and every run can be undone from History.
4. Analyse your catalog. In the SEO Editor, click Analyze all content. It scores every product, collection, page and post, and flags duplicate product descriptions.
5. Work through the lowest scores. Filter by “Needs work” and improve your most important products first.
6. Validate your schema. Use the schema validator in Tools on a product page. If your theme also prints product schema, follow the Theme setup steps to remove the duplicate.

What’s in this release

Rilea SEO for Shopify is being built in phases, and this download is version 0.1.0. It includes the dashboard and settings, the SEO editor with live content analysis, title and description templates, the bulk grid editor, find and replace, CSV import and export with undo, and structured data for products, collections, articles and pages, plus FAQ, breadcrumb, table of contents and HowTo blocks.

Redirects and the 404 monitor, sitemaps and IndexNow, link reports and site audits, local SEO and image SEO are on the roadmap. They already appear in the app’s menu and show a placeholder until they ship. The changelog lists what changes in each release.

Updating

To update, download the new version, copy your .env across, run npm install, and deploy as before. Migrations run automatically on Fly.io; on other hosts, run npx prisma migrate deploy. Then run npm run deploy so Shopify picks up any changes to the theme extension or webhooks.

Uninstalling

When a store uninstalls the app, its sessions end but its settings are kept, so a reinstall picks up where it left off. Shopify sends a data removal request 48 hours later, and the app then deletes everything it stored for that store. SEO titles, descriptions and alt text saved to Shopify’s own fields stay in place.

Troubleshooting

The dashboard says the embed isn’t active

Open the theme editor, go to App embeds, make sure Rilea SEO is switched on, and save. Then click Check again. Remember that the embed is per theme.

Pages and blog posts don’t update automatically

Shopify only sends change notifications for products and collections. Pages and posts are kept fresh by a sync every 15 minutes, which needs the worker and Redis running.

Schema appears twice

Your theme probably prints its own. Run the schema validator in Tools, then follow Theme setup’s instructions for your theme.