Bookly App Documentation

1. Prerequisites

For optimal compatibility and performance, we highly recommend using the exact versions listed below.

2. Environment Setup

Select your operating system below to view the setup instructions.

3. Change Android Package Name

First, you have to find out the existing applicationId. You can find it out from the top of the /android/app/build.gradle.kts file.

Now select the application ID and press command + shift + r or for Windows ctrl + shift + r, place your preferred package name in the replace input box, and then click on the Replace All button.

4. Firebase Setup

Step 1: Create a Firebase Project

• Go to Firebase Console.
• You will see "Get started by setting up a firebase project" or "Create a new Firebase project". Click there.
• Enter your project name, check the Firebase terms checkbox, and click Continue.
• Click Continue after finishing each step/page until you see the "project preparing" page.
• It takes a little time to prepare your project. When the project is ready, click Continue. This will navigate you to the project overview page.

Step 2: Add Android App

• From the Project Overview page, find the option to Add app and click it.
• Select Android.
• Give your package name and click Register app.
• Download the google-services.json file.
• Replace the existing file with your downloaded file in <project>/android/app/google-services.json.

Step 3: Add iOS App

• Go back to Add app and select iOS.
• Add your iOS bundleId and click Register app.
• Download the GoogleService-Info.plist file.
• Replace the existing file with your downloaded file in <project>/ios/Runner/GoogleService-Info.plist.

Video Tutorials

If you prefer a visual guide, you can also watch the videos below for a complete setup walkthrough:

• Easy way using CLI:
  Setup Flutter Firebase using FlutterFire CLI
• Manual setup:
  How to Setup Firebase in Flutter 2025 || Flutter Firebase Setup for Android and IOS

5. Social Sign In Config

To enable social authentication methods for your app, you need to configure the providers in your Firebase console.

• Go to the Firebase Console and select your previously created project.

• Tap Authentication from the left menu.
• Select the Sign-in method tab.
• From the Sign-in providers section, you need to enable the desired authentication methods.

• Enable Google, Apple, and Email/Password providers.

You need to place your Apple Service ID and Redirect URL in the project configuration file located at lib/core/config/app_config.dart.

For detailed instructions on how to set up your Service ID and Redirect URL, please follow this guide:

• Implementing Apple ID Sign-Up and Login for Flutter Android

6. Change App Name

You need to set your app name in three different places: within your application's localization files, Android manifest, and iOS configuration file.

Localization Files

• Go to <project>/lib/core/localization.
• Open en_us.dart, find app_name, and replace the value "Bookly" with your preferred app name.
• Follow the same process for bn_bd.dart and ar_sa.dart, placing your preferred app name in the respective files.

Android

• Open <project>/android/app/src/main/AndroidManifest.xml.
• Change the value of the android:label property.

android:label="YOUR_APP_NAME"

iOS

• Open <project>/ios/Runner/Info.plist.
• Update the value directly below the CFBundleName key.

<key>CFBundleName</key>
<string>YOUR_APP_NAME</string>

7. Change App Logo / Placeholder Image and Icon

To change the App logo and App Icon, you need to follow these steps:

App Logo & Placeholder Image

• Go to <project>/assets/images/ and replace bookly_logo.png and place_holder_image.jpg with your own images.

App Icon

You can generate your app icon using the tools shown in this tutorial:

• How to generate an App Icon

• For Android: Go to /android/app/src/main/res and replace all mipmap folders with your <generated icon>/android folder.
• For iOS: Go to /ios/Runner and replace the existing Assets.xcassets folder with your generated Assets.xcassets folder.

8. API Customization

To connect the Bookly app to your own backend server, you must update the API endpoint configurations.

• Navigate to <project>/lib/core/network and open the api_endpoints.dart file.
• Replace the default baseUrl and searchApi strings with your own backend URLs.
• Update the remaining API paths (like homeApi, categoriesApi, etc.) to match your backend routing structure.

9. Localization (Language Customization)

Bookly supports multi-language capabilities. You can easily add new languages, remove existing ones, or set a default app language by following these steps.

Add a New Language

• Go to <project>/lib/core/localization/translations.
• Create a new Dart file modeled after an existing one (e.g., if you are adding French, you can name it fr_fr.dart).
• Copy the code structure from an existing translation file (like en_us.dart) into your new file.
• Rename the map variable (e.g., from enUS to frFR), and translate all the string values on the right side of the colons to your new language.

• Once your translation file is ready, navigate to <project>/lib/core/localization/config/language_config.dart.
• Locate the languages list inside the LanguageConfig class.
• Add a new LanguageModel block to this list, filling in your language name, country code, and referencing the translation map variable you just created.

Set the Default Language

• The app automatically uses the first language in the languages list as the default.
• To set your preferred language as the default, simply move its corresponding LanguageModel to the very top of the list in language_config.dart.

Remove a Language

• To remove a language from the app, open language_config.dart and delete its LanguageModel from the list.
• For clean code, you can also delete the corresponding translation Dart file from the translations folder.

10. AdMob Customization

To start earning revenue through ads, you need to integrate your own AdMob Unit IDs for both Android and iOS.

Update AdMob Unit IDs

The app configuration uses a conditional check (kDebugMode) to automatically switch between Test IDs (during development) and Production IDs (when live).

• Open the configuration file located at <project>/lib/core/config/app_config.dart.
• Locate the AdMob variables section within the AppConfig class.
• Replace the production value (the string after the colon :) with your actual AdMob Unit IDs for Banner and Rewarded ads. Leave the first string as the test ID.

• How to Create AdMob Account and Ad Unit IDs

Update AdMob Application IDs

In addition to the Unit IDs, you must configure your AdMob Application IDs in the native Android and iOS configuration files.

• Android: Open <project>/android/app/build.gradle.kts.
• Scroll down to the buildTypes section.
• Inside the getByName("release") block, locate manifestPlaceholders["admobAppId"] and replace the value with your actual Android AdMob App ID. (You can leave the one under the "debug" block as the default Google test ID).

• iOS: Open <project>/ios/Runner/Info.plist.
• Locate the GADApplicationIdentifier key and replace the string value directly below it with your actual iOS AdMob App ID.

<key>GADApplicationIdentifier</key>
<string>YOUR_IOS_ADMOB_APP_ID</string>

11. In-App Purchase Configuration (RevenueCat)

Bookly uses RevenueCat to handle In-App Purchases (subscriptions and one-time purchases) seamlessly across Android and iOS platforms. Follow these steps to configure your products.

Update RevenueCat API Keys

• Open your app configuration file at <project>/lib/core/config/app_config.dart.
• Replace the revenuecatAndroidKey and revenuecatIOSKey values with your actual API keys from your RevenueCat dashboard.

Create Products in Google Play Console (and App Store)

• Log into your Google Play Console (and repeat similarly for App Store Connect).
• Create an In-App Product for your one-time purchase.
• Create a Subscription for your recurring plans.

Connect Stores to RevenueCat

• Before importing products, ensure your app stores (Google Play & App Store Connect) are properly linked to RevenueCat.
• Follow the official guide here: RevenueCat - Connect an App Store.

Import Products & Configure Offerings in RevenueCat

• Import the products you created in the Play Console/App Store into your RevenueCat account.

• Set up your Entitlements.
• CRITICAL: Ensure that your Entitlement Identifier in RevenueCat matches exactly what is shown in the screenshot below.

• Configure your Offerings.
• CRITICAL: Ensure that your Offering IDs in RevenueCat match exactly what is defined in your app_config.dart file (e.g., bookly_subscriptions and bookly_onetime).

12. Build and Release

Build for Android (APK)

Run the following command to build the APK:

flutter build apk

This command will compile your Flutter code and generate the APK file. You can find the APK in the build/app/outputs/flutter-apk directory inside your project folder. The APK file will be named something like app-release.apk or app-debug.apk.

Prepare for Google Play Store (App Bundle)

Before deploying to the Play Store, additional configuration is needed. You must create an upload keystore.

1. Create an upload keystore

Run the following command at the command line. On macOS or Linux, use the following command:

keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA \
        -keysize 2048 -validity 10000 -alias upload

On Windows, use the following command in PowerShell:

keytool -genkey -v -keystore $env:USERPROFILE\upload-keystore.jks `
        -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 `
        -alias upload

2. Replace the Keystore File

After generating upload-keystore.jks, replace the existing project bookly-keystore.jks with your new upload-keystore.jks in the <project>/android/app directory.

3. Update Key Properties

Update storePassword, keyPassword, and storeFile with your own credentials in <project>/android/key.properties.

4. Update App Version

Update your app version in <project>/android/app/build.gradle.kts.

5. Generate the App Bundle

Now you have completed all the release configurations. Generate the app bundle using the following command:

flutter build appbundle

After a successful build, you will find your app bundle in <project>/build/app/outputs/bundle/release/app-release.aab. Now you can upload it to your Google Play Console.

Build for iOS

There is no general way to generate apps for iOS locally without the Apple ecosystem. Apple doesn’t allow you to install apps via direct download. If you want to install it on your iOS device for testing, you can run it directly using Xcode. For deploying to production, please follow the official Flutter documentation here: https://docs.flutter.dev/deployment/ios

Run on a Physical iOS Device

• Configure Xcode: Open Xcode and go to Xcode > Settings... > Accounts. Sign in with your Apple ID (create a free account at developer.apple.com if needed). Add your Apple ID and select your team (usually your personal name for free accounts).
• Enable Developer Mode (iOS 16 and later): On your iOS device, go to Settings > Privacy & Security. Scroll to Developer Mode and toggle it ON. Restart the device if prompted.
• Trust the Developer: Connect your iOS device to your Mac via a USB cable. On the device, you may see a prompt to “Trust This Computer?” Tap Trust and enter your passcode. In Xcode, open Window > Devices and Simulators. Select your device and ensure it’s listed as connected.
• Verify Device Detection: Run the following command in your terminal:

  flutter devices

  This lists your iOS device (e.g., iPhone 14 (ios)). If the device doesn’t appear, check the USB connection and ensure Xcode recognizes the device.
• Run the App: In your Flutter project directory, run:

  flutter run

  If multiple devices are connected, specify the device:

  flutter run -d iPhone-14

Example: Running on an iPhone 13

• Connect the iPhone to your Mac.
• Enable Developer Mode in Settings > Privacy & Security.
• Trust the computer when prompted.
• Run flutter devices to confirm detection (e.g., iPhone 13 (ios)).
• Execute:

  flutter run -d iPhone-13

13. Backend Setup (NestJS API)

The backend powers both the mobile app and the admin panel. Set this up first — the app and admin panel cannot run without it.

Step 1: Install dependencies

• Extract the backend folder onto your server or local machine.
• Open a terminal in that folder and run:

  npm ci

Step 2: Create the database

• Create an empty PostgreSQL database:

  createdb bookly

• Or from inside psql:

  CREATE DATABASE bookly;

Step 3: Configure your environment

• Copy the example file:

  cp .env.example .env

• Open .env and fill in the required values below. Every other variable is optional — the matching feature simply stays switched off until you configure it.

Step 4: First run

• Start the server:

  npm run start:dev

• On the first boot against an empty database the server creates the role rows and your administrator account. Look for this line in the console:

  Superadmin bootstrap complete for admin@your-domain.com

• Open http://localhost:5008/api/docs to confirm the API is running. You should see the Swagger documentation page.

Step 5: Lock it down after the first login

Once you have signed into the admin panel successfully, make these three changes in .env and restart the server:

• Set DB_SYNC=false. Leaving it on lets schema changes be applied automatically, which you do not want on a live database.
• Delete the BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD lines. They are only needed once.
• Change your administrator password from inside the admin panel.

Step 6: File storage

Book covers, avatars, banners and the book files themselves (EPUB/PDF) need somewhere to live. The backend picks a storage driver automatically — the first fully configured one wins:

• Cloudflare R2 — recommended for production.
• Bunny.net — alternative CDN.
• Local disk — the fallback. Files go to the uploads/ folder and are served from /uploads/. No configuration needed, which is why a fresh install works straight away.

To use Cloudflare R2, fill in all of these in .env:

CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_R2_ACCESS_KEY_ID=
CLOUDFLARE_R2_SECRET_ACCESS_KEY=
CLOUDFLARE_R2_BUCKET=
CLOUDFLARE_R2_ENDPOINT=
CLOUDFLARE_R2_PUBLIC_URL=

Step 7: Optional integrations

All of these are switched off by default. The server starts and runs normally with every one of them unconfigured, so set up only what you need.

FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n"

Step 8: Going live with PM2

• Build the project:

  npm ci
  npm run build

• Open prod.config.js and change cwd to the folder you deployed into.
• Start it:

  pm2 start prod.config.js --env production

• Check the logs:

  pm2 logs bookly_backend --lines 30

Step 9: nginx configuration

If you serve the API through nginx, use the settings below. Both matter:

client_max_body_size 50m;

location / {
    proxy_pass http://127.0.0.1:5008;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

• client_max_body_size must be at least as large as your HTTP_BODY_LIMIT (default 50mb), otherwise book uploads fail with a 413 error.
• The X-Forwarded-For header lets the backend see each visitor's real IP address. Without it every visitor looks like the same person to the rate limiter, and they all get blocked together.

Step 10: Security settings

These are enabled out of the box. You may want to tune them for your deployment:

Troubleshooting

14. Admin Panel Setup (Next.js)

The admin panel is where you manage books, authors, users, subscriptions and everything else in your store. Complete the backend setup (section 13) first — the panel is only a front-end for that API.

Step 1: Install dependencies

• Extract the admin panel folder.
• Open a terminal in that folder and run:

  npm ci

Step 2: Point it at your backend

• Copy the example file:

  cp .env.example .env

• Open .env and set the three required values:

Step 3: Run it

• Start the development server:

  npm run dev

• Open http://localhost:3000.
• Sign in with the BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD you set in the backend's .env file.

Step 4: Going live

• Build the panel:

  npm ci
  npm run build

• Start it directly:

  npm run start

  This runs on port 4000. To use a different port, edit the start script in package.json (for example next start -p 8080).
• Or run it under PM2, which keeps it alive and restarts it after a reboot:

  pm2 start prod.config.js --env production

  Remember to set cwd in prod.config.js to your deployment folder first.

CORS_ORIGINS=https://admin.your-domain.com

What you can manage

Multi-language content

Books, authors, publishers and categories can hold a separate title and description per language. The language tabs shown in the panel come from NEXT_PUBLIC_APP_LOCALES.

Troubleshooting

15. API Reference

This section covers the request and response formats you will work with most often. The complete, always-current reference for all 166 endpoints is the Swagger UI served by your own backend:

http://localhost:5008/api/docs

Swagger is generated from the source code, so it can never drift out of date. Use Authorize there to paste a token and try any endpoint live.

Conventions

The response envelope

Every response — success or failure — uses the same outer shape.

Single item

{
  "success": true,
  "status_code": 200,
  "data": { }
}

Lists

List endpoints add a pagination block. Some also add counts, which are totals across the whole resource and are not affected by your current search filter.

{
  "success": true,
  "status_code": 200,
  "data": [ ],
  "pagination": {
    "total": 120,
    "page": 1,
    "limit": 20,
    "totalPages": 6,
    "has_next": true,
    "has_prev": false,
    "counts": {
      "total_non_deleted": 120,
      "published_live": 98,
      "draft": 15,
      "pending": 7
    }
  }
}

Common list query parameters: page, limit, search, sort, status.

Errors

{
  "success": false,
  "status_code": 401,
  "error": "Unauthorized",
  "message": "Authorization token is missing. Send a Bearer token in the Authorization header.",
  "timestamp": "2026-09-19T10:30:00.000Z"
}

Validation failures return message as an array of strings, one per invalid field:

{
  "success": false,
  "status_code": 400,
  "error": "Validation Error",
  "message": [
    "fullName must be longer than or equal to 2 characters",
    "otp_token must be a string"
  ],
  "timestamp": "2026-09-19T10:30:00.000Z"
}

Multilingual fields

Titles, names and descriptions are objects keyed by language code, not plain strings. Which languages are accepted comes from APP_LOCALES.

{
  "title": {
    "en": "Moby Dick",
    "bn": "মোবি ডিক",
    "ar": "موبي ديك",
    "hi": "मोबी डिक"
  }
}

You do not have to send every language. Any you leave out come back as an empty string.

Authentication

Sign-up is a three-step flow

Registration is protected by an email one-time code, so it takes three calls.

Step 1 — request a code. POST /api/v1/auth/otp/send

{
  "email": "jane.doe@example.com",
  "purpose": "register"
}

purpose is one of register, forgot_password or email_verify.

Step 2 — verify the code. POST /api/v1/auth/otp/verify

{
  "email": "jane.doe@example.com",
  "purpose": "register",
  "otp": "482913"
}

The response contains an otp_token. It is short-lived — its lifetime is OTP_TOKEN_EXPIRES_IN, 10 minutes by default.

Step 3 — create the account. POST /api/v1/auth/register

{
  "fullName": "Jane Doe",
  "email": "jane.doe@example.com",
  "password": "StrongPa$$123",
  "otp_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",

  "device_id": "9774d56d682e549c",
  "fcm_token": "fKx9...",
  "platform": "android",
  "device_name": "Google Pixel 8",
  "app_version": "1.0.0"
}

Login

POST /api/v1/auth/login

{
  "email": "jane.doe@example.com",
  "password": "StrongPa$$123"
}

Response:

{
  "success": true,
  "status_code": 201,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "sub": "84138aab-093d-467d-834d-b902a2738c71",
      "email": "jane.doe@example.com",
      "roles": ["user"]
    },
    "subscription": {
      "is_active": false,
      "plan": "free",
      "subscription_id": null,
      "plan_id": null,
      "plan_slug": null,
      "plan_name": null,
      "status": null,
      "billing_cycle": null,
      "starts_at": null,
      "expires_at": null,
      "gateway": null,
      "can_read_subscription_books": false
    }
  }
}

user.sub is the user's UUID. Store both tokens; send the access token on every request.

Refreshing an expired token

Access tokens expire after JWT_EXPIRES_IN (4 hours by default). When a request returns 401, exchange your refresh token for a new pair rather than forcing the user to log in again.

POST /api/v1/auth/refresh

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Other auth endpoints: POST /auth/logout, POST /auth/forgot-password, POST /auth/reset-password, POST /auth/change-password, POST /auth/firebase (social sign-in).

Reading the catalogue

Book list

GET /api/v1/books?page=1&limit=20&search=moby — returns the paginated envelope shown above.

Book details

GET /api/v1/books/{id} — send the user's token so the response reflects what that reader is entitled to.

{
  "success": true,
  "status_code": 200,
  "data": {
    "id": "9e3fffc1-edb0-4390-b33e-52a3fd239ef5",
    "title": { "en": "Moby Dick", "bn": "মোবি ডিক" },
    "description": { "en": "..." },
    "author": {
      "id": "…", "name": { "en": "Herman Melville" },
      "image_url": "https://api.example.com/uploads/authors/x.jpg",
      "total_books": 12
    },
    "file_path": "https://api.example.com/uploads/books/x.epub",
    "preview_file_path": "",
    "cover_url": "https://api.example.com/uploads/covers/x.jpg",
    "total_chapters": 135,
    "is_favorite": false,
    "language": "English",
    "dominant_color": "#2B3A42",
    "categories": [ { "id": "…", "name": { "en": "Fiction" } } ],
    "access_control": {
      "can_access": true,
      "access_type": "purchase",
      "purchased_at": "2026-09-01T10:00:00.000Z",
      "expires_at": null,
      "is_free": false,
      "is_ads_supported": false,
      "is_subscribable": true,
      "is_rentable": true,
      "is_lifetime_purchasable": true
    },
    "pricing": {
      "currency": "USD",
      "rent_price": 2.99,
      "rent_discount_percent": 0,
      "lifetime_price": 9.99,
      "lifetime_discount_percent": 0,
      "rent_duration_in_days": 30
    },
    "review": { }
  }
}

Creating content (admin)

Admin endpoints need a token belonging to a user with the admin role. Multilingual fields are sent as objects.

POST /api/v1/categories

{
  "name": { "en": "Fiction", "bn": "কল্পকাহিনী" },
  "description": { "en": "Novels and short stories" },
  "slug": "fiction"
}

Response:

{
  "success": true,
  "status_code": 201,
  "data": {
    "id": "e00f2495-11d0-4bc0-abc4-5cd3ceb0f440",
    "type": null,
    "name": { "en": "Fiction", "bn": "কল্পকাহিনী", "ar": "" },
    "thumbnail": null,
    "color": null,
    "description": { "en": "Novels and short stories", "bn": "", "ar": "" },
    "total_books": 0,
    "see_all": false,
    "books": []
  }
}

File uploads

Uploads use multipart/form-data, not JSON.

POST /api/v1/uploads/file
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <binary>

Limits: images up to 10 MB, EPUB/PDF up to 100 MB. Exceeding the limit returns 413 — if that happens on a server, raise client_max_body_size in nginx as well (section 13).

Endpoint groups

16. Database Schema

Bookly uses PostgreSQL with 44 tables. You normally never touch them directly — the backend creates everything on first run — but this section is here for anyone integrating with the data or reviewing the structure before deploying.

The schema file

A complete, ready-to-run SQL file ships with the backend at database/schema.sql. Use it if you prefer to create the schema manually, or to review it up front:

createdb bookly
psql -d bookly -f database/schema.sql

Set DB_SYNC=false in your .env afterwards, so the backend does not try to manage the schema as well.

Conventions

• Every main table has id (UUID v4), is_deleted, created_at and updated_at.
• Deletes are soft — rows are flagged with is_deleted = true rather than removed, so nothing is lost by accident.
• Column names are snake_case.
• Multilingual values are stored as jsonb, e.g. {"en": "Moby Dick", "bn": "মোবি ডিক"}.
• Money is numeric, never floating point.
• Timestamps are timestamptz (UTC).

Tables by area

Key tables

users

Roles are many-to-many via user_roles → roles, so one account can hold several roles.

books

book_access — who may read what

This is the table the reader's entitlement check reads. A row grants one user access to one book.

Enum values

These are real PostgreSQL enum types, so the database itself rejects anything outside the list.

Backing up

# Back up
pg_dump -h "$DB_HOST" -U "$DB_USER" -d "$DB_NAME" > bookly-backup.sql

# Restore
psql -h "$DB_HOST" -U "$DB_USER" -d "$DB_NAME" -f bookly-backup.sql

17. FAQ & Common Build Errors

The problems buyers hit most often, and what fixes them. If your issue is not here, please get in touch — we are happy to help.

Before anything else

Flutter app — build errors

Unsupported class file major version / Gradle fails immediately

Your Java version is wrong. Install Java 21.0.9 and point Android Studio at it in Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JDK. Then:

flutter clean
flutter pub get

Execution failed for task ':app:processDebugGoogleServices'

google-services.json is missing, or its package name does not match your app. Download a fresh one from your Firebase project and place it at android/app/google-services.json. The package_name inside it must equal the applicationId in android/app/build.gradle.kts. See section 4.

Could not resolve all files for configuration / Gradle download stalls

Usually a network or cache problem. Clear the caches and retry:

cd android
./gradlew clean
cd ..
flutter clean
flutter pub get

If it still fails, delete the Gradle cache (~/.gradle/caches) and let it download again.

Version solving failed / dependency conflicts after flutter pub get

flutter clean
rm pubspec.lock
flutter pub get

The lock file ships with the package so you get the exact versions we tested. Only delete it if you have deliberately changed a dependency.

Minimum supported Gradle version / Android Gradle Plugin errors

Open the project with the bundled Gradle wrapper rather than a system Gradle. Always open the project root in Android Studio, not the android/ folder on its own.

iOS: CocoaPods errors or missing pods

cd ios
pod repo update
pod install --repo-update
cd ..
flutter clean
flutter pub get

Requires CocoaPods 1.16.2 or newer (pod --version). On Apple Silicon, if pod install fails try arch -x86_64 pod install.

iOS: Signing for "Runner" requires a development team

Open ios/Runner.xcworkspace in Xcode, select the Runner target, go to Signing & Capabilities and choose your Apple developer team. See section 12.

The app builds but shows a blank screen or no books

It cannot reach the backend. Check in this order:

• Is the backend running? Open /api/docs in a browser.
• Is the API address in the app correct (section 8)?
• On a real device, localhost means the phone. Use your computer's LAN IP or a public address.
• Android blocks plain HTTP by default — use HTTPS for anything other than local testing.
• Have any books been added and published in the admin panel? Drafts do not appear in the app.

Backend

Sign-up fails with 400 "SMTP not configured"

Registration sends an email one-time code, so it needs a working mail server. Set MAIL_ENABLED=true and fill in the SMTP_* values (section 13, step 7). Existing accounts can still log in without SMTP — only new sign-ups are blocked.

No tables were created

DB_SYNC=true is required on the first run. Alternatively load database/schema.sql by hand (section 16).

"Superadmin bootstrap complete" never appears, and I cannot log in

The first admin is only created when the database has no users at all. If you have already created one, the bootstrap is skipped by design. Either use the original account, or start from an empty database.

Warning at startup: "Firebase is not configured"

Expected when you have not set up push notifications. The server runs normally; push and Firebase sign-in are simply disabled until you add the FIREBASE_* values.

Error: listen EADDRINUSE — port already in use

# See what is using the port
lsof -i :5008
# Stop it, or pick another port in .env
PORT=5009

Files keep landing in uploads/ instead of Cloudflare R2

R2 needs all of CLOUDFLARE_R2_ACCESS_KEY_ID, CLOUDFLARE_R2_SECRET_ACCESS_KEY, CLOUDFLARE_R2_BUCKET, CLOUDFLARE_R2_ENDPOINT and CLOUDFLARE_R2_PUBLIC_URL. If one is missing it falls back to local disk without an error message. CLOUDFLARE_R2_PUBLIC_URL is the one people forget.

413 when uploading a book

Raise client_max_body_size in nginx to at least your HTTP_BODY_LIMIT (section 13, step 9), then reload nginx.

429 Too Many Requests when logging in

The brute-force limiter. Wait a minute, or raise AUTH_RATE_LIMIT_MAX. If all your users are being limited at once, nginx is not forwarding X-Forwarded-For, so everyone looks like one visitor — see section 13, step 9.

PM2 starts, then the app immediately stops

pm2 logs bookly_backend --lines 50

Usually a missing .env in the folder named by cwd in prod.config.js, or wrong database credentials.

Admin panel

Every page is empty and the browser console shows 404s

NEXT_PUBLIC_API_URL is missing the /api/v1 ending. It must be, for example, https://api.your-domain.com/api/v1. Fix it and run npm run build again.

Covers and images do not load

Either NEXT_PUBLIC_IMAGE_URL wrongly ends in /uploads (the paths already contain it), or your CDN hostname is not allowed — add it to NEXT_PUBLIC_EXTRA_IMAGE_HOSTS.

CORS errors in the console

Add the admin panel's address to CORS_ORIGINS in the backend .env, then restart the backend.

I changed .env but nothing happened

NEXT_PUBLIC_* values are compiled into the browser bundle. Run npm run build and restart.

General questions

Do I need the backend to run the app?

Yes. The app is a client for the Bookly API — the catalogue, accounts, purchases and reading progress all live there.

Can I host the backend and admin panel on the same server?

Yes. Run them on different ports (5008 and 4000 by default) and put nginx in front of both.

Can I use MySQL instead of PostgreSQL?

No. The schema relies on PostgreSQL-specific features such as jsonb for multilingual fields and native enum types.

Which languages are supported?

English, Bangla, Arabic and Hindi out of the box, including right-to-left layout for Arabic. Set the active list in APP_LOCALES (backend) and NEXT_PUBLIC_APP_LOCALES (admin panel) — they must match. Adding another language is covered in section 9.

How do I add a book?

In the admin panel: Books → Add Book. Upload the EPUB or PDF and a cover, fill in the details for each language, set pricing, then publish. Draft books do not appear in the app.

Do I have to use PipraPay?

No. It is off by default. The payment layer is provider-based, and Google Play / Apple in-app purchases are supported separately.

Where are uploaded files stored?

Cloudflare R2, Bunny.net, or the local uploads/ folder — whichever is configured first. See section 13, step 6.

How do I stop people sharing book download links?

Set PROTECT_BOOK_FILES=true. Links then carry an expiring signature and cannot be reused elsewhere. Your apps need no changes. Note that paid books are already withheld from readers who have not bought them.

Can I remove AdMob or in-app purchases?

Yes — both are configurable. See sections 10 and 11.

18. Support

If you need help, reach out using any of the channels below.

• WhatsApp: +8801609563816
• Email: mosarofdiu123@gmail.com
• LinkedIn: Mosaraf Hossain

19. Changelog

Version 1.1.1 – 19 Sep 2026

• New: Backend API (NestJS + PostgreSQL) now included in the package. See section 13.
• New: Admin panel (Next.js) now included in the package. See section 14.
• New: Push notification support added.
• New: Premium PDF reader plugin integrated.
• Improvement: Sign Up flow updated — email sign up now uses OTP verification sent over SMTP, replacing the previous Firebase email/password sign up.
• Improvement: Full app configured for Android modern edge-to-edge display.
• Improvement: UI/UX upgraded across the app.
• Improvement: Many more enhancements throughout the app.
• Fix: Fixed several minor bugs.

Version 1.1.0 – 14 Mar 2026

• New: Added attractive in-app version update dialog.
• New: Custom home promotional banner dialog for free users.
• New: Anti-screenshot protection added for ebooks.
• Improvement: UI/UX refinements for a smoother user experience.
• Improvement: Core engine optimized for much faster book loading.
• Fix: Resolved reader layout issues on specific devices.

Version 1.0.0 – 3 Mar 2026

• Initial Release