From ZIP file to production.

Know what is included

Circliva is delivered as two coordinated products. Keep both original archives unchanged as a backup before you customize anything.

Use this setup order

Following this order avoids domain, package-name, Firebase, and license mismatches.

Prepare a compatible server

On shared hosting, confirm that AllowOverride is enabled or that LiteSpeed honors the included rules. The package is designed for Apache/LiteSpeed; customers do not need to create proxy routes.

Prepare the domain and database

cd /home/USER/public_html
chown -R USER:USER .
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chmod -R 750 storage public/uploads

Install through install.php

1. Open https://your-domain.com/install.php.
2. Confirm every server readiness check is green.
3. Enter the Circliva purchase code issued by Lumaqode.
4. Enter the exact HTTPS website URL without an extra path.
5. Enter the MySQL connection values.
6. Create the first administrator account using a private email and strong password.
7. Select Verify & install Circliva once and wait for completion.
8. Sign in at https://your-domain.com/admin/.

Post-install checks

• The home page opens at the domain root.
• /api/v1/health returns a healthy API response.
• /admin/ accepts the administrator account.
• storage/install.lock exists.
• Opening install.php again reports that installation is locked.

Understand the server license

Circliva verifies a purchase before installation and stores a signed runtime license on the customer server. Database and administrator credentials never leave the customer server.

Repair a missing server license binding

Circliva 1.0.3 adds a safe recovery flow for installations created before their central domain binding was recorded. It repairs licensing only; it does not reinstall the site or change the database.

1. Back up .env, storage/license/, the database, and local uploads.
2. Use the update archive matching the installed version: Circliva-Update-v1.0.0-to-v1.0.3.zip, v1.0.1-to-v1.0.3, or v1.0.2-to-v1.0.3.
3. Extract the update into the existing Circliva document root and allow the package to merge its files.
4. Open https://your-domain.com/update.php, sign in as a super administrator, and complete the update.
5. If the dashboard still requests licensing attention, open https://your-domain.com/install.php?repair=1.
6. Enter the original purchase code. The repair request must use the exact domain already assigned to that purchase.
7. Return to /admin/ and confirm the license status is active.

php scripts/activate-existing-install.php --repair

Configure the platform from /admin

Use a super_admin account for initial configuration, then create narrower roles for daily operations.

Install the development tools

• Flutter stable with the Dart SDK required by the included pubspec.yaml.
• Android Studio and Android SDK for Android builds.
• JDK 17 for the Android Gradle toolchain.
• macOS and a current supported Xcode for iOS builds.
• A real Android/iOS device for push notification and sign-in tests.

flutter --version
flutter doctor -v
cd /path/to/circliva
flutter pub get
dart format --output=none --set-exit-if-changed lib
flutter analyze

flutter analyze can inspect the source before the app license is generated. Starting the application itself requires a valid signed licenses.dart.

Choose final Android and iOS identifiers

Use identifiers you own, typically based on a reversed company domain. These values must match stores, Firebase, Google Sign-In, and the Circliva app license.

Generate and install licenses.dart

1. Finish the server installation on the final HTTPS domain.
2. Finalize the Android package name and iOS bundle identifier.
3. Open the Circliva License Generator.
4. Enter the same valid purchase code and exact installation URL.
5. Enter the exact Android and iOS identifiers.
6. Generate and download licenses.dart.
7. Replace lib/core/license/licenses.dart in the Flutter source.
8. Run the quick verification commands below.

test -f lib/core/license/licenses.dart && echo "License file found"
flutter pub get
flutter analyze

Run and verify the application

flutter devices
flutter run -d DEVICE_ID

• The onboarding and authentication screens open without a license error.
• Register and sign in against the new server.
• Images and videos use HTTPS URLs from the licensed domain.
• Home, reels, stories, profile, search, chat, marketplace, wallet, ads, and settings load.
• Light/dark theme and a second screen size are checked.

Use hot reload during development. A full rebuild is only necessary after changing native Android/iOS files, dependencies, Firebase configuration, signing, or release mode.

Sign and build the Android release

The included project targets Android SDK 24 or newer and uses Java/JVM 17. Firebase is activated only when android/app/google-services.json exists.

Create a private upload keystore

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

Copy android/key.properties.example to android/key.properties, then enter the keystore path, alias, store password, and key password. Never commit either file.

flutter clean
flutter pub get
flutter build appbundle --release
flutter build apk --release

Sign and archive the iOS application

1. Use macOS with Xcode and an active Apple Developer account.
2. Open the iOS project in Xcode and select the Runner target.
3. Set the final bundle identifier and Apple Development Team.
4. Set the deployment target to iOS 15.0 or newer.
5. Enable Push Notifications and Background Modes → Remote notifications when using FCM.
6. Run on a real device before archiving.

flutter clean
flutter pub get
flutter build ios --release

For App Store Connect, use Xcode: Product → Archive, validate the archive, then distribute it. Complete privacy details, screenshots, support URL, privacy URL, and account-deletion information before review.

Do not confuse the three Firebase configurations

Create the Firebase project

1. Open the Firebase Console and create a project.
2. Enable Google Analytics only if your privacy plan requires it.
3. Add one Android app using the exact Android package name.
4. Add one iOS app using the exact iOS bundle identifier.
5. Open Cloud Messaging and confirm the Firebase Cloud Messaging API is available.
6. Configure Authentication → Sign-in method → Google only when you are ready to expose the Google button.

Circliva can still read in-app notifications from its API when Firebase is disabled, but native background push requires the complete client and server Firebase setup.

Connect the Android app

1. In Firebase Console, open Project settings → Your apps and register an Android app using the exact value of applicationId.
2. Add the SHA-1 and SHA-256 fingerprints for the debug, upload, and release signing certificates.
3. Select Download google-services.json.
4. Remove any example or old Firebase file from the Flutter project.
5. Copy the downloaded file to android/app/google-services.json. Keep this exact name; do not rename it.
6. Confirm the package_name inside its Android client matches the application's applicationId.
7. Run flutter clean, fetch dependencies, and rebuild the app.

cd android
./gradlew signingReport
cd ..

Connect iOS and APNs

1. In Firebase Console, open Project settings → Your apps and register an Apple app using the exact Runner bundle identifier.
2. Select Download GoogleService-Info.plist.
3. Remove any example or old Firebase plist from the Flutter project and copy the downloaded file to ios/Runner/GoogleService-Info.plist.
4. Open ios/Runner.xcworkspace in Xcode.
5. If the file is not visible inside the yellow Runner group, right-click Runner and select Add Files to “Runner”…, then choose GoogleService-Info.plist.
6. Enable Copy items if needed and select the Runner target in Add to targets.
7. Open Runner → Build Phases → Copy Bundle Resources and confirm GoogleService-Info.plist appears exactly once.
8. Under Runner → Signing & Capabilities, add Push Notifications.
9. Add Background Modes and check Remote notifications.
10. In Apple Developer, create an APNs authentication key.
11. Upload the APNs key, Key ID, and Apple Team ID in Firebase → Project settings → Cloud Messaging.
12. Run flutter clean, fetch dependencies, rebuild, and test notifications on a real device.

Upload the Admin SDK JSON safely

1. In Google Cloud/Firebase project settings, create or download a service-account Admin SDK JSON for the Circliva project.
2. Sign in as super_admin and open /admin/?page=settings.
3. Find Push notification credentials → Firebase service account.
4. Choose the JSON file and select Validate and replace.
5. Select Test connection.
6. Delete the downloaded copy from shared computers after the server test succeeds.

Start the push worker

* * * * * /usr/bin/php /home/USER/public_html/scripts/process-push.php 200 >> /home/USER/public_html/storage/logs/push.log 2>&1

Use the actual PHP CLI and project paths shown by your hosting panel. Push delivery requires device registration, notification permission, the correct client configuration, a valid Admin SDK account, and a running worker.

Configure Google Sign-In

1. Enable Google in Firebase Authentication.
2. Configure the OAuth consent screen in Google Cloud.
3. Create/confirm Android OAuth credentials for the exact package name and SHA fingerprints.
4. Create/confirm iOS credentials for the exact bundle ID and URL scheme.
5. Add the correct web/server client ID in Circliva application settings when requested.
6. In /admin/?page=settings, enable Google social login only after both platforms pass a real-device test.

If Google login is not configured, leave its dashboard switch off. The application will hide the button instead of sending customers into a broken flow.

Configure SMTP and password reset

Open /admin/?page=settings and configure SMTP host, port, encryption, username, password, sender name, sender address, and timeout. Use the built-in test email before enabling production mail.

• SPF is published for the sending domain.
• DKIM is enabled at the email provider.
• DMARC policy is configured.
• Sender address belongs to the authenticated domain.
• Password-reset email arrives and its link/OTP completes successfully.

Saved SMTP passwords are encrypted using the installation application key. Leaving a password field empty while editing preserves the existing secret.

Control OTP, WhatsApp, and optional protection

From application settings, administrators can require or disable phone verification and enable/disable the WhatsApp OTP gateway. When mandatory verification is off, customers can create and enter accounts without a forced WhatsApp code.

High-risk protection such as biometric unlock or verification for sensitive operations should remain optional after account creation unless your business rules require it.

WHATSAPP_API_URL=https://provider.example/api
WHATSAPP_API_KEY=YOUR_PRIVATE_KEY
WHATSAPP_TIMEOUT_SECONDS=10

Choose local storage or S3

The active storage provider is controlled from the administration dashboard. Start with local storage for a small installation or configure Amazon S3 / an S3-compatible provider for scalable media delivery.

AWS_ACCESS_KEY_ID=YOUR_SERVER_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_SERVER_SECRET_KEY
AWS_SESSION_TOKEN=

• The bucket CORS policy allows the exact required web origins.
• Uploads are not publicly writable.
• The configured public URL returns images and HLS files with HTTPS.
• Lifecycle rules match the business retention policy.
• A restore test has been completed before deleting local originals.

Enable FFmpeg and adaptive HLS video

With FFmpeg and FFprobe available, Circliva can create a poster and HLS renditions such as 360p, 480p, 720p, and 1080p without upscaling beyond the source. The application can then select an appropriate quality and prefetch within its bounded cache.

which ffmpeg
which ffprobe
ffmpeg -version
ffprobe -version

* * * * * /usr/bin/php /home/USER/public_html/scripts/process-video.php >> /home/USER/public_html/storage/logs/video.log 2>&1

Set the real binary paths in the server environment when your host installs them outside /usr/bin. Confirm that the PHP user may execute both binaries and write to the selected storage provider.

Configure Agora live streaming

Circliva creates every RTC token on the PHP server. The Agora App Certificate is encrypted with APP_KEY, never included in Flutter, and never returned by the public configuration API.

1. Create an Agora project in the Agora Console and enable an App Certificate.
2. Open /admin/?page=settings and locate Agora credentials.
3. Enter the 32-character App ID and App Certificate.
4. Choose the RTC token lifetime and maximum broadcast duration.
5. Enable comments/reactions if required, then enable Agora live streaming.
6. Open the application on two real devices: start a broadcast on one and join from the LIVE story ring on the other.

* * * * * /usr/bin/php /home/USER/public_html/scripts/process-live-streams.php >> /home/USER/public_html/storage/logs/live-streams.log 2>&1

• Camera and microphone permission descriptions are present on Android and iOS.
• Host, audience, token renewal, mute, camera switch, comments, and reactions work on real devices.
• Followers-only broadcasts are invisible to non-followers.
• Interrupted hosts disappear automatically after the stale-session timeout.
• Agora usage limits and billing alerts are configured before launch.

Configure payments, wallet, marketplace, and ads

Platform commission is calculated on the amount actually paid after the allowed discount. Review Apple and Google payment rules before activating external checkout in store-distributed builds.

Publish languages and legal documents

Circliva stores mobile translations on the server. Administrators can update language values centrally; the application downloads and caches published versions rather than requiring a new store build for every wording change.

• Create and review each language in ?page=translations.
• Keep translation keys stable after applications are released.
• Test both left-to-right and right-to-left layouts.
• Edit Privacy Policy, Terms of Use, and account-deletion information in ?page=legal.
• Confirm that legal links are readable before registration and available from settings.
• Ask customers to actively accept the required documents during registration.

php scripts/import-translations.php
php scripts/publish-legal-documents.php

Public legal URLs are available under /privacy/, /terms/, and /account-deletion/.

Install the required cron jobs

* * * * * /usr/bin/php /home/USER/public_html/scripts/process-push.php 200 >> /home/USER/public_html/storage/logs/push.log 2>&1
* * * * * /usr/bin/php /home/USER/public_html/scripts/process-video.php >> /home/USER/public_html/storage/logs/video.log 2>&1
* * * * * /usr/bin/php /home/USER/public_html/scripts/process-live-streams.php >> /home/USER/public_html/storage/logs/live-streams.log 2>&1
*/15 * * * * /usr/bin/php /home/USER/public_html/scripts/process-account-deletions.php >> /home/USER/public_html/storage/logs/account-deletions.log 2>&1

Run each command manually once as the same hosting user, then inspect its log. Do not run overlapping workers at an aggressive interval if your hosting plan has strict CPU/process limits.

Harden the production installation

• Use HTTPS only and redirect HTTP to HTTPS.
• Keep APP_ENV=production and APP_DEBUG=false.
• Do not modify or remove the root .htaccess.
• Confirm direct requests to .env, storage/, vendor/, database/, and scripts/ are denied.
• Use a dedicated least-privilege database user.
• Restrict super_admin; create role-specific administrator accounts.
• Enable administrator MFA when available and revoke unused sessions.
• Review the admin audit log after balance, payment, role, verification, and moderation changes.
• Rate-limit public authentication and upload routes at the hosting/firewall layer.
• Rotate exposed keys immediately; deleting a message or Git commit is not enough.

Back up and update safely

Minimum backup set

• Full MySQL dump with routines/triggers if used.
• .env and storage/license/.
• storage/secrets/ including Firebase server credentials.
• public/uploads/ when local storage is active.
• Customized source, legal content, and current Flutter license file.
• Android keystore and Apple signing access stored separately.

mysqldump --single-transaction --routines --triggers \
  -u DB_USER -p DB_NAME | gzip > circliva-$(date +%F).sql.gz

Safe update sequence

1. Check the update notes on this documentation page and compare system requirements.
2. Back up database and files.
3. Choose the update ZIP whose from version exactly matches the installed version.
4. Test the update on a staging copy with an authorized staging license.
5. Extract the update ZIP into the existing document root without deleting .env, storage/, or public/uploads/.
6. Open /update.php, authenticate as a super administrator, and complete the guided update.
7. Clear relevant caches, restart workers, and run smoke tests.
8. Keep the old release and rollback backup until verification is complete.

Production checklist

Solve common setup problems

Official resources and support