docs: deployment guide, with supporting config and integrations. (#1836)

Fleshing out deployment guide. To support it, added a sync service config page in the api docs section and specific integrations pages for various deployment platforms. Quite a lot to review here. Check out the: - [Sync service config page at /docs/api/config](https://deploy-preview-1836--electric-next.netlify.app/docs/api/config) - [Updated Typescript client page at /docs/api/clients/typescript](https://deploy-preview-1836--electric-next.netlify.app/docs/api/clients/typescript) - [Deployment page at /docs/guides/deployment](https://deploy-preview-1836--electric-next.netlify.app/docs/guides/deployment) - Individual integration pages in the "Integrations" section of the docs nav, e.g.: [AWS](https://deploy-preview-1836--electric-next.netlify.app/docs/integrations/aws), [React](https://deploy-preview-1836--electric-next.netlify.app/docs/integrations/react) and [Supabase](https://deploy-preview-1836--electric-next.netlify.app/docs/integrations/supabase) Note that: - Netlify has a one-click-deploy form that uses https://github.com/electric-sql/standalone-basic-example - [Render](https://deploy-preview-1836--electric-next.netlify.app/docs/integrations/supabase) has a [Blueprint repo](https://github.com/electric-sql/render-blueprint) that also uses the same standalone-basic-example As @KyleAMathews commented on Discord, these might be better to include in the monorepo and update using a GitHub action. Perhaps that can be a subsequent Issues / PR. The integrations also include a [Phoenix page](https://deploy-preview-1836--electric-next.netlify.app/docs/integrations/phoenix) which is based on merging #1833 and publishing an updated release for https://hexdocs.pm/electric_phoenix/0.1.0-dev-2/Electric.Phoenix.html Note that the deployment docs all assume a single `DATABASE_URL`, i.e.: this is pre multi-tenant. --------- Co-authored-by: Kyle Mathews <[email protected]>
electric-sql · Nov 5, 2024 · 64e61d1 · 64e61d1
1 parent 4d6bab8
commit 64e61d1
Show file tree

Hide file tree

Showing 110 changed files with 2,571 additions and 119 deletions.
diff --git a/website/.vitepress/config.mts b/website/.vitepress/config.mts
@@ -46,6 +46,7 @@ export default defineConfig({
       'css',
       'javascript',
       'jsx',
+      'nginx',
       'shellscript',
       'sql',
       'tsx',
@@ -147,8 +148,8 @@ export default defineConfig({
           items: [
             { text: 'Auth', link: '/docs/guides/auth' },
             { text: 'Shapes', link: '/docs/guides/shapes' },
-            { text: 'Deployment', link: '/docs/guides/deployment' },
             { text: 'Installation', link: '/docs/guides/installation' },
+            { text: 'Deployment', link: '/docs/guides/deployment' },
             { text: 'Troubleshooting', link: '/docs/guides/troubleshooting' },
             { text: 'Writing your own client', link: '/docs/guides/writing-your-own-client' },
           ]
@@ -166,21 +167,46 @@ export default defineConfig({
               ],
               collapsed: false
             },
+            { text: 'Config', link: '/docs/api/config' }
+          ]
+        },
+        {
+          text: 'Integrations',
+          collapsed: false,
+          items: [
             {
-              text: 'Integrations',
+              text: 'Frameworks',
               items: [
-                // { text: 'MobX', link: '/docs/api/integrations/mobx' },
-                { text: 'React', link: '/docs/api/integrations/react' },
-                // { text: 'Redis', link: '/docs/api/integrations/redis' },
-                // { text: 'TanStack', link: '/docs/api/integrations/tanstack' },
+                { text: 'LiveStore', link: '/docs/integrations/livestore' },
+                { text: 'MobX', link: '/docs/integrations/mobx' },
+                { text: 'Next.js', link: '/docs/integrations/next' },
+                { text: 'Phoenix', link: '/docs/integrations/phoenix' },
+                { text: 'React', link: '/docs/integrations/react' },
+                { text: 'Redis', link: '/docs/integrations/redis' },
+                { text: 'TanStack', link: '/docs/integrations/tanstack' },
               ],
-              collapsed: false
+            },
+            {
+              text: 'Platforms',
+              items: [
+                { text: 'AWS', link: '/docs/integrations/aws' },
+                { text: 'Cloudflare', link: '/docs/integrations/cloudflare' },
+                { text: 'Crunchy', link: '/docs/integrations/crunchy' },
+                { text: 'Digital Ocean', link: '/docs/integrations/digital-ocean' },
+                { text: 'Expo', link: '/docs/integrations/expo' },
+                { text: 'Fly.io', link: '/docs/integrations/fly' },
+                { text: 'GCP', link: '/docs/integrations/gcp' },
+                { text: 'Neon', link: '/docs/integrations/neon' },
+                { text: 'Netlify', link: '/docs/integrations/netlify' },
+                { text: 'Render', link: '/docs/integrations/render' },
+                { text: 'Supabase', link: '/docs/integrations/supabase' }
+              ]
             }
           ]
         },
         {
           text: 'Reference',
-          collapsed: true,
+          collapsed: false,
           items: [
             { text: 'Alternatives', link: '/docs/reference/alternatives' },
             { text: 'Benchmarks', link: '/docs/reference/benchmarks' },

diff --git a/website/.vitepress/theme/custom.css b/website/.vitepress/theme/custom.css
@@ -87,7 +87,9 @@
   --ddn-color: #D0BCFF;
   --pglite-color: #F6F95C;
 
-  --vp-code-font-size: 0.925em;
+  --vp-code-bg: var(--vp-c-bg-elv);
+  --vp-code-color: #9ECBFF;
+  --vp-code-font-size: 0.875em;
   --vp-font-family-base: OpenSauceOne, ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
   --vp-font-family-mono: SourceCodePro, ui-monospace, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
 }
@@ -421,22 +423,24 @@ a.no-visual:hover {
   text-align: center;
   font-weight: 600;
   white-space: nowrap;
-  transition: color 0.25s, border-color 0.25s, background-color 0.25s;
+  transition: color 0.25s, border-color 0.25s, background-color 0.25s !important;
 }
 .VPButton.brand {
   background-color: var(--vp-button-brand-bg);
   border-color: var(--vp-button-brand-border);
-  color: var(--vp-button-brand-text);
+  color: var(--vp-button-brand-text) !important;
 }
 .VPButton.brand:hover {
   background-color: var(--vp-button-brand-hover-bg);
   border-color: var(--vp-button-brand-hover-border);
-  color: var(--vp-button-brand-hover-text);
+  color: var(--vp-button-brand-hover-text) !important;
+  opacity: 1 !important;
 }
 .VPButton.brand:active {
   background-color: var(--vp-button-brand-active-bg);
   border-color: var(--vp-button-brand-active-border);
-  color: var(--vp-button-brand-active-text);
+  color: var(--vp-button-brand-active-text) !important;
+  opacity: 1 !important;
 }
 
 .VPButton.electric,
@@ -451,6 +455,16 @@ a.no-visual:hover {
   border-color: var(--pglite-color);
   color: var(--vp-c-bg);
 }
+.VPButton.small {
+  border-radius: 16px;
+  padding: 0 16px;
+  line-height: 34px;
+  font-size: 13.5px;
+}
+.VPButton.vspace {
+  margin-top: 6px;
+  margin-bottom: 6px;
+}
 
 .img-row {
   display: grid;
@@ -560,7 +574,10 @@ iframe {
 .vp-doc .custom-block {
   margin: 24px 0;
 }
-
+.custom-block {
+  border-radius: 12px;
+  padding: 19px 21px 11px;
+}
 .custom-block-no-title {
   margin-bottom: 10px !important;
 }
@@ -576,6 +593,11 @@ iframe {
   padding: 24px 0 !important;
 }
 
+pre {
+  max-width: 100%;
+  overflow-x: scroll;
+}
+
 ul.benefits {
   color: var(--vp-c-text-1) !important;
 

diff --git a/website/blog/posts/2024-07-17-electric-next.md b/website/blog/posts/2024-07-17-electric-next.md
@@ -27,7 +27,7 @@ Electric Next was a clean rebuild of the Electric sync engine that now forms the
 
 We created a new repo and started by porting the absolute minimum code necessary from the [previous repo](https://github.com/electric-sql/electric-old). Once we were confident that Electric Next was the way forward, we froze the old system and moved the new code into our main repo at [https://github.com/electric-sql/electric](https://github.com/electric-sql/electric).
 
-The new approach provides an [HTTP API](/docs/api/http) for syncing [Shapes](/docs/guides/shapes) of data from Postgres. This can be used directly or via [client libraries](/docs/api/clients/typescript) and [integrations](/docs/api/integrations/react). It's also simple to write your own client in any language.
+The new approach provides an [HTTP API](/docs/api/http) for syncing [Shapes](/docs/guides/shapes) of data from Postgres. This can be used directly or via [client libraries](/docs/api/clients/typescript) and [integrations](/docs/integrations/react). It's also simple to write your own client in any language.
 
 ## Why build a new system?
 
@@ -237,7 +237,7 @@ You can sync data into:
 
 - apps, replacing data fetching with data sync
 - development environments, for example syncing data into [an embedded PGlite](/product/pglite)
-- edge workers and services, for example maintaining a low-latency [edge data cache](/docs/api/integrations/redis)
+- edge workers and services, for example maintaining a low-latency [edge data cache](/docs/integrations/redis)
 - local AI systems running RAG, as per the example below
 
 <figure>
@@ -273,7 +273,7 @@ At the time of writing this document, we are early in the development of Electri
 However, even just with the first release of Electric Next you can already sync partial subsets of data from a Postgres database into a wide variety of clients and environments, for example:
 
 - syncing data into local apps using the [TypeScript](/docs/api/clients/typescript) and [Elixir](/docs/api/clients/elixir) clients
-- replacing hot-path data fetching and database queries in apps using [React](/docs/api/integrations/react), [MobX](/docs/api/integrations/react) and [TanStack](/docs/api/integrations/tanstack)
+- replacing hot-path data fetching and database queries in apps using [React](/docs/integrations/react), [MobX](/docs/integrations/react) and [TanStack](/docs/integrations/tanstack)
 - maintain live caches with automatic invalidation, as per [our Redis example](https://github.com/electric-sql/electric/blob/main/examples/redis-sync/src/index.ts)
 
 ### Roadmap

diff --git a/website/docs/api/clients/elixir.md b/website/docs/api/clients/elixir.md
@@ -2,24 +2,51 @@
 outline: deep
 ---
 
-# Elixir Client
+# Elixir client
 
-The Elixir client is being developed in [electric-sql/electric-next/pull/38](https://github.com/electric-sql/electric-next/pull/38). At the moment it provides a GenStage producer that can be used to stream a Shape as per:
+Electric provides an [Elixir client](#how-to-use) that wraps the [HTTP API](/docs/api/http) into a higher-level stream interface and a [Phoenix integration](#phoenix-integration) that adds sync to your Phoenix application.
+
+## How to use
+
+The [`Electric.Client`](https://hex.pm/packages/electric_client) library allows you to stream [Shapes](/docs/guides/shapes) into your Elixir application. It's published to Hex as the [`electric_client`](https://hex.pm/packages/electric_client) package.
+
+### Stream
+
+The client exposes a [`stream/3`](https://hexdocs.pm/electric_client/Electric.Client.html#stream/3) that streams a [Shape Log](/docs/api/http#shape-log) into an [`Enumerable`](https://hexdocs.pm/elixir/Enumerable.html):
 
 ```elixir
-opts = [
-  base_url: "http://...",
-  shape_definition: %Electric.Client.ShapeDefinition{
-    table: "..."
-  }
-]
+Mix.install([:electric_client])
 
-{:ok, pid, stream} = Electric.Client.ShapeStream.stream(opts)
+{:ok, client} = Electric.Client.new(base_url: "http://localhost:3000")
+
+stream = Electric.Client.stream(client, "my_table", where: "something = true")
 
 stream
 |> Stream.each(&IO.inspect/1)
 |> Stream.run()
 ```
 
-See the [shape_stream_test.exs](https://github.com/electric-sql/electric-next/blob/thruflo/elixir-client/elixir_client/test/electric/client/shape_stream_test.exs) for more details.
+You can materialise the shape stream into a variety of data structures. For example by matching on insert, update and delete operations and applying them to a Map or an Ecto struct. (See the [redis-sync](https://github.com/electric-sql/electric/blob/main/examples/redis-sync/src/index.ts) example and Typescript [Shape class](https://github.com/electric-sql/electric/blob/main/packages/typescript-client/src/shape.ts) for reference).
+
+### Ecto queries
+
+The `stream/3` function also supports deriving the shape definition from an [`Ecto.Query`](https://hexdocs.pm/ecto/Ecto.Query.html):
+
+```elixir
+import Ecto.Query, only: [from: 2]
+
+query = from(t in MyTable, where: t.something == true)
+
+stream = Electric.Client.stream(client, query)
+```
+
+See the documentation at [hexdocs.pm/electric_client](https://hexdocs.pm/electric_client) for more details.
+
+## Phoenix integration
+
+Electric also provides an [`Electric.Phoenix`](https://hex.pm/packages/electric_phoenix) integration allows you to:
+
+- sync data into a [front-end app](/docs/integrations/phoenix#front-end-sync) from a Postgres-backed Phoenix application; and
+- add real-time streaming from Postgres into Phoenix LiveView via [Phoenix.Streams](/docs/integrations/phoenix#liveview-sync)
 
+See the [Phoenix framework integration page](/docs/integrations/phoenix) for more details.