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.

Cloud feature

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 unless the code is already taken (short codes are globally unique)
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

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

1. Sign up at linkforty.com and create your organization (workspace). See Organizations.
2. 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

tip

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.

1. Go to Migration in the dashboard.
2. Choose LinkForty Core as the source platform.
3. Upload your CSV, then run Preview / Validate first — it checks for short-code conflicts without writing anything.
4. 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.

Short codes

Short codes are preserved when possible. Because codes are globally unique across LinkForty, if a code is already taken the link still imports but receives a new generated code — and your original code is recorded on the imported link's metadata.

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 via templateId or templateSlug).
• 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:

1. In the dashboard, add your domain under Settings → Domains.
2. 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.

Cut over deliberately

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. Only two things change:

• baseUrl → your Cloud link domain (the custom domain from Step 4).
• apiKey → your Cloud key from Step 1.

LinkForty.initialize({
  baseUrl: 'https://go.yourapp.com', // your Cloud link domain
  apiKey: 'YOUR_CLOUD_KEY',          // from the dashboard
});

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.

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.
• 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.