ZinklySocial Documentation

ZinklySocial is a professional Laravel 13 social / forum application with real-time features, a full admin panel, and a built-in ZIP-based update system. It's the core platform that ZinklyChat, EchoAI, NotiLive and LingoSync all plug into over its REST + WebSocket API.

What's included

Technology stack

Every failed install traces back to one of these three things — check them before you upload anything.

Minimum requirements

Required PHP extensions

Recommended server specs

Pick the guide that matches your access level below, then follow it start to finish — don't mix steps between guides.

The recommended way to install ZinklySocial — a full install on a fresh Linux server (Ubuntu/Debian) with SSH access.

1. Connect and upload

   # from your machine
   ssh youruser@your-server-ip
   
   # create the app directory
   mkdir -p /home/user/web/yourdomain.com/zinkly-app
   cd /home/user/web/yourdomain.com
   
   # upload zinkly-social.zip here (scp / sftp), then:
   unzip zinkly-social.zip -d zinkly-app
   cd zinkly-app

2. Install dependencies

   # PHP dependencies — no dev packages in production
   composer install --no-dev --optimize-autoloader
   
   # JS dependencies + build frontend assets
   npm install
   npm run build

3. Configure environment

   cp .env.example .env
   php artisan key:generate
   nano .env   # set DB_*, APP_URL, MAIL_*, etc.

4. Database & storage

   php artisan migrate --force --seed
   php artisan storage:link

5. Permissions & caching

   chmod -R 775 storage bootstrap/cache
   chown -R www-data:www-data storage bootstrap/cache   # match your web server's user
   
   php artisan config:cache
   php artisan route:cache
   php artisan view:cache

6. Point the web server — the document root must point at the app's public/ folder, never the app root.

   # example Nginx root
   root /home/user/web/yourdomain.com/zinkly-app/public;

The app lives directly inside public_html; HestiaCP's Nginx vhost is pointed at public_html/public as the document root. One folder, no file-shuffling.

1. Create the domain and database
   • HestiaCP → Web → Add Web Domain (e.g. social.yourdomain.com)
   • Once DNS resolves to the server, enable SSL → Let's Encrypt
   • HestiaCP → DB → Add Database — note the generated name, username, password
2. Upload the app straight into public_html

   ssh user@your-server-ip
   cd /home/user/web/social.yourdomain.com/public_html
   
   # upload zinkly-social.zip here, then:
   unzip zinkly-social.zip -d .
   rm zinkly-social.zip
   
   composer install --no-dev --optimize-autoloader
   npm install && npm run build

3. Point the document root at public_html/public — HestiaCP serves public_html by default; Laravel must never be web-accessible at its root.

   Newer HestiaCP (UI method — no SSH needed for this step): HestiaCP → Web → your domain → Edit → check Custom document root → Point to: your domain → Directory: public. HestiaCP shows the resulting path live and saves/reloads Nginx for you:

   /home/user/web/social.yourdomain.com/public_html/public

   Older HestiaCP without that toggle — edit the vhost by hand instead:

   nano /home/user/conf/web/social.yourdomain.com/nginx.ssl.conf
   # find the "root" line and point it at:
   root /home/user/web/social.yourdomain.com/public_html/public;
   
   nginx -t && systemctl reload nginx

4. Configure & migrate

   cd /home/user/web/social.yourdomain.com/public_html
   cp .env.example .env
   php artisan key:generate
   
   nano .env
   # DB_DATABASE, DB_USERNAME, DB_PASSWORD → from HestiaCP → DB
   # APP_URL=https://social.yourdomain.com
   
   php artisan migrate --force --seed
   php artisan storage:link
   chmod -R 775 storage bootstrap/cache
   chown -R user:user storage bootstrap/cache   # the HestiaCP system user
   
   php artisan config:cache && php artisan route:cache && php artisan view:cache

The document root still has to end up pointing at the app's public/ folder — that never goes away, SSH or not. Editing index.php's paths to fake it is fragile and breaks on the next update, so don't do that.

1. Upload and extract the main ZIP outside your public web folder if your panel allows it (a sibling folder to public_html) — matches the SSH/HestiaCP layout, done over FTP.
2. Point the document root at that folder's public/ subfolder, using your host's panel (usually under "Advanced" or "Domain Settings" — no SSH needed). No such field? Ask your host's support — it's a one-line change on their end.
3. Only if truly impossible: upload the main ZIP's contents directly into public_html, then from the small installer ZIP upload just installation.php into that same folder.
4. Add the protection block below to the top of public_html/.htaccess regardless of which option you used.
5. Visit https://yourdomain.com/installation.php to configure the database.
6. Then visit https://yourdomain.com/install to finish setup, run migrations, and create your admin account.

.htaccess protection (add regardless of the option above)

# top of public_html/.htaccess, above Laravel's own rules
RewriteRule ^(app|bootstrap|config|database|lang|resources|routes|storage|tests|vendor|\.env|composer\.(json|lock))(/.*)?$ - [F,L]

ZinklySocial sends browser push notifications for new messages, incoming calls, likes, comments, and follows — even when the site isn't open in a tab. This needs its own Firebase project; it's a separate setup step from the server install above, and the app runs fine without it, just without push.

1. Create a Firebase project

1. Create the project at console.firebase.google.com → Add project.
2. Register a web app — Add app → Web, name it after your site, and copy the SDK config it shows you: API key, Project ID, Auth domain, Storage bucket, Messaging sender ID, App ID.
3. Generate a Web Push certificate — Project settings (gear icon) → Cloud Messaging tab → under "Web configuration" → generate one. This is your VAPID key.
4. Generate a service account key — Project settings → Service accounts tab → Generate new private key. This downloads a JSON file — keep it secret, it's used server-side only.

2. Configure the credentials

Go to AdminCP → Integrations and fill in the Firebase section with the web app values from step 1:

These save to the database and take effect immediately — no deploy or cache clear needed — and override any matching FIREBASE_WEB_* values in .env if both are set.

The service account JSON from step 1.4 is different: a server-side secret, and it is never entered into AdminCP. Upload it somewhere outside your public web root, then set one .env value:

FIREBASE_CREDENTIALS=/absolute/path/outside/public_html/firebase-service-account.json

Then pick up the new path:

php artisan config:clear && php artisan config:cache

3. How it turns on for a visitor

Nothing further to configure — this happens automatically once step 2 is saved.

• The browser does not prompt for permission the instant someone logs in — a dismissible "Get notified here" banner appears first; the actual permission prompt only fires after the visitor clicks it.
• Once granted, the browser registers a service worker at /firebase-messaging-sw.js (already included in the app — nothing to configure), which receives pushes while the tab is closed or backgrounded.
• The resulting device token is saved to the device_tokens table, which is what sends pushes on the server side.

Testing & troubleshooting

• Send a test push from Firebase Console → Cloud Messaging → Send test message using a registration token from the device_tokens table, before debugging app code.
• Nothing arriving? Check storage/logs/laravel.log for "FCM send failed" — usually a missing/invalid FIREBASE_CREDENTIALS path or a revoked service account key.
• A token FCM reports as invalid (app uninstalled, unsubscribed, site data cleared) is pruned automatically from device_tokens on the next send — no manual cleanup needed.

Fixes for the issues that come up most, in the order they're worth checking.

Pages look unstyled — step by step

This means the browser couldn't load app.css/app.js from public/build/. In order of likelihood:

1. Stale browser cache — every npm run build generates new hashed filenames and deletes the old ones; an old cached page pointing at a deleted file 404s. Hard refresh: Ctrl+Shift+R (Cmd+Shift+R on Mac).
2. Build never ran or failed — check public/build/manifest.json exists and is recent (ls -la public/build); re-run npm run build if missing or stale.
3. Cached views referencing an old manifest — run php artisan view:clear (then view:cache in production) after any frontend rebuild.
4. Nginx not serving /build/ correctly — confirm the document root actually points at public/, not the app root.

That's the surface. Once you're logged into AdminCP, System → Documentation carries this same guide plus everything else — environment variables, updates, backups, integrations — and the full version-by-version changelog.