Migrate from Self-Hosted Core to Cloud
LinkForty Cloud runs on the same open-source engine as self-hosted Core — Cloud is Core plus multi-tenant workspaces, billing, custom domains, and a managed dashboard. Because the two share the same link model, moving to Cloud is mostly a matter of copying your link definitions into a Cloud workspace, repointing your domain, and updating your SDK configuration.
This guide moves you to LinkForty Cloud. If you'd rather keep running your own infrastructure, see Cloud vs Self-Hosted. It's the same engine either way, so you can always take your data back out and self-host again later.
What migrates — and what doesn't
Be clear-eyed about scope before you start:
| Data | Migrates? | Notes |
|---|---|---|
| Link definitions (short code, destinations, UTM) | ✅ Yes | Via the CSV importer or the links API |
| Short codes | ✅ Usually | Preserved. Codes are unique per workspace; see the note below for links without a template |
| Deep link params, targeting rules, custom schemes, attribution windows | ⚠️ API only | The CSV importer carries URLs + UTM only; recreate via the API to keep these |
| Historical analytics (clicks, installs, conversions) | ❌ No | Analytics start fresh in Cloud — there is no import for historical events |
| Device fingerprints / in-flight install attribution | ❌ No | Cannot be moved |
| App token | ➖ Doesn't apply | Core doesn't have one. Your Cloud workspace gets its own when you create it, and you add it to your app in Step 5 |
The practical approach: migrate your link definitions, accept a clean analytics slate, and run Core and Cloud in parallel during cutover so no live links break.
Step 1 — Create your Cloud workspace
- Sign up at linkforty.com and create your organization (workspace). See Organizations.
- In the dashboard, create an API key under Settings → API Keys. The full key is shown once, on creation — copy it now; you'll need it for the SDK and (optionally) the links API.
Step 2 — Export your links from Core
Core doesn't ship a CSV export, so pull your links out and reshape them into the importer's format. Core's links table columns already match the importer's headers, so this is straightforward. Two options:
Option A — Core API. Call Core's list endpoint and convert the JSON to CSV:
curl "https://your-core-host/api/links?userId=YOUR_USER_ID"
Option B — Direct SQL. Export straight from Core's Postgres database:
COPY (
SELECT short_code, title, original_url,
ios_app_store_url, android_app_store_url, web_fallback_url,
utm_parameters->>'source' AS utm_source,
utm_parameters->>'medium' AS utm_medium,
utm_parameters->>'campaign' AS utm_campaign,
utm_parameters->>'term' AS utm_term,
utm_parameters->>'content' AS utm_content
FROM links
) TO STDOUT WITH CSV HEADER;
Either way, produce a CSV with exactly these headers:
short_code,title,original_url,ios_app_store_url,android_app_store_url,web_fallback_url,utm_source,utm_medium,utm_campaign,utm_term,utm_content
Download a ready-made template from the Migration page in the dashboard to confirm the exact column order before you export.
Step 3 — Import into Cloud
The dashboard's migration tool has a first-class LinkForty Core importer — it's the default source.
- Go to Migration in the dashboard.
- Choose LinkForty Core as the source platform.
- Upload your CSV, then run Preview / Validate first — it checks for short-code conflicts without writing anything.
- Choose a conflict strategy and import:
- Skip (default) — leave existing links untouched.
- Overwrite — replace a matching link.
- Rename — keep both; the new one gets a suffixed short code.
Imported links count toward your plan's link limit; an import that would take you over it is refused before anything is written. Short codes are unique per workspace, so your codes are preserved even when another workspace uses the same ones. A code your workspace already has is handled by the conflict strategy you choose. A link imported without a template is served at /{code} alone, so its code must not be used by any other workspace; if it is, that row is reported as an error and you can recreate the link with a template through the links API.
Alternative: recreate links via the API (richer fields)
The CSV importer carries URLs, title, and UTM only. If your links use deep link parameters, targeting rules, custom schemes, or per-link attribution windows, recreate them through the links API instead, which accepts those fields — and set customCode to preserve your short code. The links API accepts your API key (Authorization: Bearer <key>):
POST /api/links— one link (requires a template viatemplateIdortemplateSlug).POST /api/links/bulk-create— up to 100 links per request.
See Creating Links for the full field reference.
Step 4 — Repoint your custom domain
If your Core links run on your own domain (e.g. go.yourapp.com), move it to Cloud so existing links keep resolving:
- In the dashboard, add your domain under Settings → Custom Domains.
- Update your domain's CNAME to point at:
go.linkforty.com
Cloudflare provisions SSL automatically (usually 5–15 minutes). Once verified, requests to your domain are served by Cloud.
Keep your Core instance running until DNS has fully propagated and you've confirmed links resolve on Cloud. Changing the CNAME is what actually moves live traffic — do it once you're ready.
Step 5 — Reconfigure your SDK
Point your apps at Cloud instead of your Core server:
baseUrl→https://api.linkforty.com. Your links can stay on your custom domain from Step 4: the app token tells the SDK which hosts are yours.appToken→ your workspace's app token (Workspace Settings → App Token). Required: installs without a valid one aren't counted. Each workspace has its own token, so use the one from the workspace you're migrating into. Cloud matches installs only to your own links with it.apiKey→ your Cloud key from Step 1, only if the app creates links.
LinkForty.initialize({
baseUrl: 'https://api.linkforty.com',
appToken: 'at_your_app_token', // from Workspace Settings
apiKey: 'YOUR_CLOUD_KEY', // only if the app creates links
});
The SDK talks to Cloud's /api/sdk/v1/* endpoints on that host. See SDK integration and the React Native SDK for the exact configuration. On the web, drop in the Web Pixel.
Versions of your app already out there. Core doesn't use an app token, so released versions don't send one. Your Cloud workspace requires it, so if those versions reach Cloud, for example through your custom domain, their installs aren't counted at first. Nothing breaks for those users. Go to Settings → App Configuration and choose Count installs without a token to count them while people update. The option appears once those installs start arriving, and installs left out before you choose it aren't added back. The requirement returns after 30 days with none of these installs.
Step 6 — Verify and finish cutover
- Tap a few migrated links and confirm they open the right screen, store, or web fallback.
- Confirm new clicks and installs are showing up in the Cloud dashboard. Test an install from a build that has the app token: it should be counted with no warning in Settings → App Configuration.
- Once you're confident everything resolves on Cloud, decommission your self-hosted Core instance.
Your links now run on Cloud — with the managed dashboard, custom domains, team features, and analytics — and no self-hosted infrastructure to maintain.