Skip to content

Commit c9e46b3

Browse files
chenbachenba
committed
docs: add how-to on deploying with docker compose
1 parent 25c852a commit c9e46b3

5 files changed

Lines changed: 123 additions & 130 deletions

File tree

‎docs/src/SUMMARY.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,11 +29,11 @@
2929
[Mozilla Accounts Server - FxA](mozilla-accounts.md)
3030

3131
- [How To Guides](how-to/index.md)
32-
- [Run Your Own FxA Server](how-to/how-to-run-fxa.md)
32+
- [Run Your Own Sync-1.5 Server with Docker](how-to/how-to-run-with-docker.md)
3333
- [Run Your Own Sync-1.5 Server (legacy)](how-to/how-to-run-sync-server.md)
3434
- [Configure Sync Server for TLS (legacy)](how-to/how-to-config-tls.md)
3535

3636
[Documentation and MdBook Notes](doc-notes.md)
3737
[Glossary of Terms](glossary.md)
3838
[Response Codes](response-codes.md)
39-
[Terms of Service](terms-of-service.md)
39+
[Terms of Service](terms-of-service.md)

‎docs/src/how-to-run-with-docker.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Run Your Own Sync-1.5 Server with Docker

‎docs/src/how-to/how-to-run-fxa.md‎

Lines changed: 1 addition & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1 @@
1-
<a id="howto_run_fxa"></a>
2-
3-
# Run Your Own Mozilla Accounts Server (Outdated)
4-
5-
The Mozilla accounts server is deployed on our systems using RPM packaging,
6-
and we don't provide any other packaging or publish official builds yet.
7-
8-
> **Note:** This guide is preliminary and vastly incomplete. If you have any
9-
> questions or find any bugs, please don't hesitate to file an issue:
10-
[Syncstorage-rs GitHub Issues](https://github.com/mozilla-services/syncstorage-rs/issues).
11-
12-
> **Note:** You might also be interested in
13-
> [this Docker-based self-hosting guide](https://github.com/michielbdejong/fxa-self-hosting)
14-
> (use at your own risk - quite out of date).
15-
16-
The Mozilla accounts server is hosted in **git** and requires **nodejs**.
17-
Make sure your system has these, or install them:
18-
19-
- **git**: <http://git-scm.com/downloads>
20-
- **nodejs**: <http://nodejs.org/download>
21-
22-
A self-hosted Mozilla accounts server requires two components:
23-
24-
- an **auth-server** that manages the accounts database
25-
- a **content-server** that hosts a web-based user interface
26-
27-
Clone the fxa repository [linked here](https://github.com/mozilla/fxa/) and follow the README to deploy your own auth-server and content-server instances. <https://github.com/mozilla/fxa/>
28-
29-
30-
Now direct Firefox to use your servers rather than the default, Mozilla-hosted
31-
ones. The procedure varies a little between desktop and mobile Firefox, and
32-
may not work on older versions of the browser.
33-
34-
---
35-
36-
## Desktop Firefox (version 52 or later)
37-
38-
1. Enter `about:config` in the URL bar.
39-
2. Right-click anywhere on the page and choose **New > String**.
40-
3. Enter `identity.fxaccounts.autoconfig.uri` for the name, and your
41-
content-server URL for the value.
42-
4. Restart Firefox for the change to take effect.
43-
44-
> **Note:** This must be set prior to loading the sign-up or sign-in page
45-
> in order to take effect, and its effects are reset on sign-out.
46-
47-
---
48-
49-
## Firefox for iOS (version 9.0 or later)
50-
51-
1. Go to **Settings**.
52-
2. Tap on the **Version number** 5 times.
53-
3. Tap **Advance Account Settings**.
54-
4. Enter your content-server URL.
55-
5. Toggle **Use Custom Account Service** to on.
56-
57-
---
58-
59-
## Firefox Preview for Android (“Fenix”)
60-
61-
- There is not yet support for using a non-Mozilla-hosted account server.
62-
- Work is being tracked in this GitHub issue:
63-
<https://github.com/mozilla-mobile/fenix/issues/3762>
64-
65-
---
66-
67-
## Firefox for Android (“Fennec”, version 44 or later)
68-
69-
1. Enter `about:config` in the URL bar.
70-
2. Search for items containing `fxaccounts`, and edit them to use your
71-
self-hosted URLs.
72-
73-
### Auth server
74-
75-
Use your auth-server URL to replace `api.accounts.firefox.com` in:
76-
77-
- `identity.fxaccounts.auth.uri`
78-
79-
### Content server
80-
81-
Use your content-server URL to replace `accounts.firefox.com` in:
82-
83-
- `identity.fxaccounts.remote.webchannel.uri`
84-
- `webchannel.allowObject.urlWhitelist`
85-
86-
### Optional: OAuth and profile servers
87-
88-
Use your OAuth and profile server URLs to replace
89-
`{oauth,profile}.accounts.firefox.com` in:
90-
91-
- `identity.fxaccounts.remote.profile.uri`
92-
- `identity.fxaccounts.remote.oauth.uri`
93-
94-
> **Important:** *After* creating the Android account, changes to
95-
> `identity.fxaccounts` prefs will be *ignored*.
96-
> If you need to change the prefs, delete the Android account using
97-
> **Settings > Sync > Disconnect…**, update the pref(s), and sign in again.
98-
>
99-
> Non-default Mozilla account URLs are displayed in the
100-
> **Settings > Sync** panel in Firefox for Android, so you should be able
101-
> to verify your URL there.
102-
103-
---
104-
105-
Since the Mozilla-hosted sync servers will not trust assertions issued by
106-
third-party accounts servers, you will also need to run your own
107-
sync-1.5 server. See [How To Run Your Own Sync-1.5 Server](./how-to-run-sync-server.md).
108-
109-
Please note that the `fxa-content-server` repository includes graphics and
110-
other assets that make use of Mozilla trademarks. If you are doing anything
111-
other than running unmodified copies of the software for personal use, please
112-
review:
113-
114-
- Mozilla Trademark Policy:
115-
<https://www.mozilla.org/en-US/foundation/trademarks/policy/>
116-
- Mozilla Branding Guidelines:
117-
<http://www.mozilla.org/en-US/styleguide/identity/mozilla/branding/>
118-
119-
You can ask for help on Matrix (chat.mozilla.org) in the **#fxa** room:
120-
<https://chat.mozilla.org/#/room/#fxa:mozilla.org>
121-
122-
---
123-
124-
### Additional reading
125-
126-
- [How to connect Firefox for Android to self-hosted Mozilla account and Firefox Sync servers](http://www.ncalexander.net/blog/2014/07/05/how-to-connect-firefox-for-android-to-self-hosted-services/)
1+
# Run Your Own FxA Server

‎docs/src/how-to/how-to-run-with-docker.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Use Docker to Deploy Your Own Sync Server
2+
3+
Mozilla publishes Docker images of its
4+
[`syncstorage-rs`](https://github.com/mozilla-services/syncstorage-rs) builds
5+
on ghcr.io. This guide provides a simple `docker compose` setup that can act as
6+
a starting point to self-host Sync.
7+
8+
Images are available for both
9+
[MySQL](https://github.com/mozilla-services/syncstorage-rs/pkgs/container/syncstorage-rs%2Fsyncstorage-rs-mysql)
10+
and
11+
[PostgreSQL](https://github.com/mozilla-services/syncstorage-rs/pkgs/container/syncstorage-rs%2Fsyncstorage-rs-postgres)
12+
as the database. The sample code will focus on MySQL. Differences in
13+
configuration or deployment steps will be noted.
14+
15+
> **Note:** At the time of writing, there are no tagged release builds
16+
> available on ghcr.io. This guide will use a build from the main development
17+
> branch.
18+
19+
## Prerequisites and Presumptions
20+
- The reader has a MySQL or PostgreSQL database up and running.
21+
- The reader is familiar with the command line interface and `docker`.
22+
- The reader is going to use [Mozilla accounts](https://accounts.firefox.com/)
23+
for authentication and authorization.
24+
- The service will be deployed at http://localhost:8000/.
25+
26+
## Docker Compose
27+
28+
Save the yaml below into a file, e.g. `docker-compose.yaml`.
29+
30+
```yaml
31+
services:
32+
syncserver:
33+
image: ghcr.io/mozilla-services/syncstorage-rs/syncstorage-rs-mysql:b16ef5064b
34+
platform: linux/amd64
35+
container_name: syncserver
36+
ports:
37+
- "8000:8000"
38+
environment:
39+
SYNC_HOST: "0.0.0.0"
40+
SYNC_PORT: "8000"
41+
SYNC_MASTER_SECRET: "${SYNC_MASTER_SECRET}"
42+
SYNC_SYNCSTORAGE__DATABASE_URL: "${SYNC_SYNCSTORAGE__DATABASE_URL}"
43+
SYNC_TOKENSERVER__DATABASE_URL: "${SYNC_TOKENSERVER__DATABASE_URL}"
44+
SYNC_TOKENSERVER__ENABLED: "true"
45+
SYNC_TOKENSERVER__RUN_MIGRATIONS: "true"
46+
SYNC_TOKENSERVER__FXA_EMAIL_DOMAIN: "api.accounts.firefox.com"
47+
SYNC_TOKENSERVER__FXA_OAUTH_SERVER_URL: "https://oauth.accounts.firefox.com"
48+
restart: unless-stopped
49+
healthcheck:
50+
test: ["CMD", "curl", "-f", "http://localhost:8000/__heartbeat__"]
51+
interval: 30s
52+
timeout: 10s
53+
retries: 3
54+
start_period: 60s
55+
```
56+
57+
Note that multiple values will be read from the environment:
58+
- `SYNC_MASTER_SECRET`: a secret used in cryptographic operations
59+
- `SYNC_SYNCSTORAGE__DATABASE_URL`: database URL for syncstorage, e.g. `mysql://sync:test@example.io/syncstorage` or `postgres://testo:@localhost/syncdb`
60+
- `SYNC_TOKENSERVER__DATABASE_URL`: database URL for tokenserver, e.g. `mysql://sync:test@example.io/tokenserver` or `postgres://testo:@localhost/syncdb`
61+
62+
The values can be directly written into the yaml as well.
63+
64+
Next, start the service with `docker compose`:
65+
66+
```sh
67+
SYNC_MASTER_SECRET=use_your_own_secret_4d3d3d3d \
68+
SYNC_SYNCSTORAGE__DATABASE_URL="mysql://sync:test@example.io/syncstorage" \
69+
SYNC_TOKENSERVER__DATABASE_URL="mysql://sync:test@example.io/tokenserver" \
70+
docker compose -f docker-compose.yaml up -d
71+
```
72+
73+
### Database Bootstrapping
74+
75+
After starting the service on a clean, uninitialized database, some bootstrapping records need to be inserted.
76+
77+
For MySQL, run
78+
```sql
79+
INSERT INTO tokenserver.services (service, pattern) VALUES ('sync-1.5', '{node}/1.5/{uid}');
80+
81+
INSERT INTO tokenserver.nodes (service, node, available, current_load, capacity, downed, backoff)
82+
VALUES (
83+
(SELECT id FROM services WHERE service = 'sync-1.5'),
84+
'http://localhost:8000',
85+
1, 0, 1000, 0, 0
86+
);
87+
```
88+
89+
For PostgreSQL, run
90+
```sql
91+
INSERT INTO nodes (service, node, available, current_load, capacity, downed, backoff)
92+
VALUES (
93+
(SELECT id FROM services WHERE service = 'sync-1.5'),
94+
'http://localhost:8000',
95+
1, 0, 1000, 0, 0
96+
);
97+
```
98+
99+
Note that `http://localhost:8000` above needs to be replaced with the actual
100+
service URL.
101+
102+
Restart the service with
103+
```sh
104+
docker compose -f docker-compose.yaml restart
105+
```
106+
107+
## Configuring Firefox
108+
109+
Firefox itself needs to be configured to use the self-hosted Sync server.
110+
111+
1. Go to `about:config` in Firefox.
112+
1. Find the `identity.sync.tokenserver.uri` configuration.
113+
1. Change the value to `http://localhost:8000/1.0/sync/1.5`.
114+
1. Restart Firefox.
115+
116+
Firefox should be using the self-hosted Sync server at this point. That can be
117+
verified by checking the logs in `about:sync-log`.

‎docs/src/how-to/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22

33
Collection of How To guides for various Sync-related operations.
44

5-
- [Run Your Own FxA Server](how-to-run-fxa.md)
5+
- [Run Your Own Sync-1.5 Server with Docker](how-to-run-with-docker.md)
66
- [Run Your Own Sync-1.5 Server (legacy)](how-to-run-sync-server.md)
7-
- [Configure Sync Server for TLS (legacy)](how-to-config-tls.md)
7+
- [Configure Sync Server for TLS (legacy)](how-to-config-tls.md)

0 commit comments

Comments
 (0)