You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
2. 2+ PowerSync API containers, 1GB memory each, 1vCPU each.
23
+
3. A 3-node MongoDB replica set, 2+GB memory each. Refer to the MongoDB documentation for deployment requirements. M10+ when using Atlas.
24
+
4. A load balancer with redundancy.
25
+
5. Run a daily compact job.
26
+
27
+
For scaling up, add 1x PowerSync API container per 100 connections. The MongoDB replica set should be scaled based on CPU and memory usage.
28
+
29
+
### Replication Container
30
+
31
+
The replication container handles replicating from the source database to PowerSync's bucket storage.
32
+
33
+
The replication process is run using the docker command `start -r sync`, for example `docker run powersync start -r sync`.
34
+
35
+
Only one process can replicate at a time. If multiple are running concurrently, you may see an error `[PSYNC_S1003] Sync rules have been locked by another process for replication`.
36
+
If you use rolling deploys, it is normal to see this error for a short duration while multiple processes are running.
37
+
38
+
Memory and CPU usage of the replication container is primarily driven by write load on the source database. A good starting point is 1GB memory and 1 vCPU for the container, but this may be scaled down depending on the load patterns.
39
+
40
+
Set the environment variable `NODE_OPTIONS=--max-old-space-size=800` for 800MB, or set to 80% of the total assigned memory if scaling up or down.
41
+
42
+
### API Containers
43
+
44
+
The API container handles streaming sync connections, as well as any other API calls.
45
+
46
+
The replication process is run using the docker command `start -r api`, for example `docker run powersync start -r api`.
47
+
48
+
Each API container is limited to 200 concurrent connections, but we recommend targeting 100 concurrent connections or less per container. This may change as we implement additional performance optimizations.
49
+
50
+
Memory and CPU usage of API containers are driven by:
51
+
1. Number of concurrent connections.
52
+
2. Number of buckets per connection.
53
+
3. Amount of data synced to each connection.
54
+
55
+
A good starting point is 1GB memory and 1 vCPU per container, but this may be scaled up or down depending on the specific load patterns.
56
+
57
+
Set the environment variable `NODE_OPTIONS=--max-old-space-size=800` for 800MB, or set to 80% of the total assigned memory if scaling up or down.
58
+
59
+
### Compact Job
60
+
61
+
We recommend running a compact job daily as a cron job, or after any large maintenance jobs. For details, see the documentation on [Compacting Buckets](/usage/lifecycle-maintenance/compacting-buckets).
62
+
63
+
Run the compact job using the docker command `compact`, for example `docker run powersync compact`.
64
+
65
+
The compact job uses up to 1GB memory for compacting, if available. Set the environment variable `NODE_OPTIONS=--max-old-space-size=800` for 800MB, or set to 80% of the total assigned memory if scaling up or down.
66
+
67
+
### Load Balancer
68
+
69
+
A load balancer is required in from of the API containers to provide TLS support and load balancing. Most cloud providers have built-in options for load balancing, such as ALB on AWS.
70
+
71
+
It is currently required to host the API container on a dedicated subdomain - we do not support running it on the same subdomain as another service.
72
+
73
+
For self-hosting, [nginx](https://nginx.org/en/) is always a good option. A basic nginx configuration could look like this:
74
+
75
+
```
76
+
server {
77
+
listen 443 ssl;
78
+
server_name powersync.example.prg;
79
+
80
+
# SSL configuration here
81
+
82
+
# Reverse proxy settings
83
+
location / {
84
+
proxy_pass http://powersync_server_ip:powersync_port; # Replace with your powersync details
If the load balancer supports health checks, it may be configured to poll the API container at `/probes/liveness`. This endpoint is expected to have a 200 response when the container is healthy. See [Healthchecks](./healthchecks) for details.
104
+
105
+
### Migrations
106
+
107
+
By default, migrations are run as part of the replication and API containers. In some cases, a migration may add signifant delay to the container startup.
108
+
109
+
To avoid this, the migrations may be run as a separate job on each update, before replacing the rest of the containers. To run the migrations, run the docker command `migrate up`, for example `docker run powersync migrate up`.
110
+
111
+
In this case, disable automatic migrations in the config:
10
112
11
113
```yaml
12
114
# powersync.yaml
@@ -16,10 +118,11 @@ migrations:
16
118
# When set to true, migrations must be triggered manually by modifying the container `command`.
17
119
disable_auto_migration: true
18
120
```
19
-
MongoDB locks ensure migrations are executed exactly once, even when multiple containers start simultaneously.
20
121
21
122
## Backups
22
123
23
124
We recommend using Git to backup your configuration files.
24
125
25
-
The sync bucket storage database doesn't require backups as it can be easily reconstructed.
126
+
None of the containers use any local storage, so no backups are required there.
127
+
128
+
The sync bucket storage database may be backed up using the recommendations for the storage database system. This is not a strong requirement, since this data can be recovered by re-replicating from the source database.
Multiple instances are not required in most cases. See the [Overview](self-hosting/lifecycle-maintenance) for details on standard horizontal scaling setups.
10
+
</Warning>
11
+
12
+
When exceeding a couple thousand concurrent connections, the standard PowerSync setup may not scale sufficiently to handle the load. In this case, we recommend you [contact us](/resources/contact-us) to discuss the options. However, we give a basic overview of using multiple PowerSync instances to scale here.
13
+
14
+
Each PowerSync "instance" is a single endpoint (URL), that is backend by:
15
+
1. One replication container.
16
+
2. Multiple API containers, scaling horizontally.
17
+
3. One bucket storage database.
18
+
19
+
This setup is described in the [Overview](self-hosting/lifecycle-maintenance).
20
+
21
+
To scale further, multiple copies of this setup can be run, using the same source database.
22
+
23
+
## Mapping user -> PowerSync endpoint
24
+
25
+
Since each PowerSync instance maintains its own copy of the bucket data, the exact list of operations and associated checksum will be different between them. This means the same client must connect to the same endpoint every time, otherwise they will have to re-sync all their data every time they switch. Multiple PowerSync instances cannot be load-balanced behind the same subdomain.
26
+
27
+
To ensure the same user always connects to the same endpoint, we recommend:
28
+
1. Do an API lookup from the client application to get the PowerSync endpoint, don't hardcode it in the application.
29
+
2. Either store the endpoint associated with each user, or compute it automatically using a hash function on the user id.
0 commit comments