Consolidate docs from readthedocs and the wiki
Fixes https://github.com/mozilla/fxa/issues/324
This commit is contained in:
vladikoff
Родитель
95438b0381
Коммит
4ee15a5a87
|
|
@ -0,0 +1,29 @@
|
|||
---
|
||||
id: faq
|
||||
title: Frequently Asked Questions
|
||||
sidebar_label: Frequently Asked Questions
|
||||
---
|
||||
|
||||
## Am I required to create a Firefox Account to use Firefox?
|
||||
No. A Firefox Account is only required for Mozilla Services that require authentication, such as Firefox Sync and advanced features on Firefox Marketplace like purchasing paid apps, adding app reviews etc.
|
||||
|
||||
## Why does Firefox Accounts require me to choose a password?
|
||||
One of the primary services that uses Firefox Accounts is Firefox Sync, which encrypts all your data client-side before submitting it to the server. The password is used to securely derive an encryption key.
|
||||
|
||||
## What information does Firefox Accounts store about the user?
|
||||
[https://developer.mozilla.org/en-US/Firefox_Accounts#Firefox_Accounts_user_data](https://developer.mozilla.org/en-US/Firefox_Accounts#Firefox_Accounts_user_data)
|
||||
|
||||
## Can I use Firefox Accounts to store user data for my application or service?
|
||||
In general no.
|
||||
|
||||
Firefox Accounts only stores information that will deliver significant user value across applications or is tightly related to the user's identity. It will not store user data for relying services. Relying Mozilla services can use Firefox Accounts for authentication, but application data storage is the responsibility of the individual applications.
|
||||
|
||||
|
||||
## Can I use my Firefox Account to log in to non-Mozilla services?
|
||||
Not initially, but it's something we'd like to support in the future.
|
||||
|
||||
## Does Firefox Accounts provide email?
|
||||
No.
|
||||
|
||||
## Is it possible to host your own Firefox Accounts service, like with Firefox Sync?
|
||||
[Yes.](https://docs.services.mozilla.com/howtos/run-fxa.html)
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
---
|
||||
id: local-development
|
||||
title: Local Development
|
||||
sidebar_label: Local Development
|
||||
---
|
||||
|
||||
Please read through the [CONTRIBUTING.md](https://github.com/mozilla/fxa/blob/master/CONTRIBUTING.md) file
|
||||
to get a better understanding of how to write a patch for Firefox Accounts.
|
||||
|
||||
# fxa-local-dev
|
||||
|
||||
Follow the README.md in the [fxa-local-dev repository](https://github.com/mozilla/fxa-local-dev)
|
||||
to get started.
|
||||
|
||||
### Updating npm shrinkwrap
|
||||
|
||||
* Install the [npmshrink](https://www.npmjs.com/package/npmshrink) tool.
|
||||
* If you are updating the fxa-content-server run `npmshrink:prod` in the root directory.
|
||||
All other repos use `npmshrink`.
|
||||
|
||||
# fxa-dev
|
||||
|
||||
We use an AWS Ansible-based docker development environment
|
||||
called [fxa-dev](https://github.com/mozilla/fxa-dev) to deploy different versions of the FxA stack.
|
||||
It can be found here [https://github.com/mozilla/fxa-dev](https://github.com/mozilla/fxa-dev) (make sure to use the `docker` branch).
|
||||
|
||||
## Notes
|
||||
|
||||
You can find a lot of important information about fxa-dev usage in its [README.md](https://github.com/mozilla/fxa-dev#usage).
|
||||
Here are some additional notes that expand on the README:
|
||||
|
||||
### SSH
|
||||
|
||||
You can ssh into the EC2 instance with `ssh ec2-user@meta-{{ whatever you configured in foo.yml }}`.
|
||||
|
||||
### Ansible Logs
|
||||
|
||||
If the box failed to deploy properly, ssh into it and check `/var/log/cloud-init-output.log`
|
||||
|
||||
The Ansible polling / update log can be found here: `/var/log/ansible/update.log`
|
||||
|
||||
### Docker Commands
|
||||
|
||||
[Build](https://docs.docker.com/engine/reference/commandline/build/)
|
||||
|
||||
```
|
||||
docker build --no-cache=true -t TAG_NAME .
|
||||
```
|
||||
|
||||
Use `--file` to specify a custom Dockerfile file like `--file Dockerfile-build`.
|
||||
|
||||
Example: `docker build --no-cache=true -t vladikoff/123done .`
|
||||
|
||||
Tag
|
||||
|
||||
```
|
||||
docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
|
||||
```
|
||||
|
||||
Example: `docker tag vladikoff/123done vladikoff/123done:oauth-keys`
|
||||
|
||||
Push
|
||||
|
||||
```
|
||||
docker push NAME[:TAG]
|
||||
```
|
||||
|
||||
Example: `docker push vladikoff/123done:oauth-keys`
|
||||
|
||||
Other
|
||||
|
||||
`docker ps` - show running containers. Keep an eye on the `NAMES` column.
|
||||
|
||||
`docker logs [NAME]` - show logs for a particular container.
|
||||
|
||||
`docker restart [NAME]` - restart a container.
|
||||
|
||||
Shell into containers
|
||||
|
||||
```
|
||||
sudo docker exec -i -t [container_name] /bin/sh
|
||||
```
|
||||
|
||||
Example: `sudo docker exec -i -t redis /bin/sh`
|
||||
|
||||
Output the arguments the process was started with:
|
||||
|
||||
```
|
||||
sudo docker exec -it auth-server sh -c 'ps aux' # finds the PID
|
||||
sudo docker exec -it auth-server sh -c 'cat /proc/8/environ | xargs -0 -n 1' # outputs args
|
||||
```
|
||||
|
||||
|
||||
### MySQL SSH Access
|
||||
|
||||
You can access the MySQL database via SSH. Here's an example configuration using Sequel Pro on macOS.
|
||||
Make sure to specify your SSH Password using a path to your private key. In this example we
|
||||
are connecting to a stack called `test62`:
|
||||
|
||||
<img src=https://i.imgur.com/T9yL9Ti.jpg width=350 />
|
||||
|
|
@ -0,0 +1,195 @@
|
|||
---
|
||||
id: android-components
|
||||
title: Building the Android Components
|
||||
sidebar_label: Building the Android Components
|
||||
---
|
||||
|
||||
## Doing a local build of the Android Components:
|
||||
|
||||
This document describes how to make local builds of the Android components in
|
||||
this repository. Most consumers of these components *do not* need to follow
|
||||
this process, but will instead use pre-built components [todo: link to this]
|
||||
|
||||
This document, and the build process itself, is a work-in-progress - please file issues (or just update the wiki!) if you notice errors or omissions.
|
||||
|
||||
## Prepare your build environment
|
||||
|
||||
*NOTE: This section is almost certainly incomplete - given it is typically
|
||||
only done once, things have probably been forgotten or over-simplified.
|
||||
Please file PRs if you notice errors or omissions here*
|
||||
|
||||
This process should work OK on Mac and Linux. It also works on [Windows via WSL by following these instructions](#using-windows).
|
||||
|
||||
Typically, this process only needs to be run once, although periodically you
|
||||
may need to repeat some steps (eg, rust updates should be done periodically)
|
||||
|
||||
At the end of this process you should have the following environment variables set up.
|
||||
|
||||
- `NDK_HOME`
|
||||
- `ANDROID_NDK_TOOLCHAIN_DIR`
|
||||
- `ANDROID_NDK_API_VERSION`
|
||||
- `ANDROID_HOME`
|
||||
- `JAVA_HOME`
|
||||
|
||||
These variables are required every time you build, so you should add them to
|
||||
a rc file or similar so they persist between reboots etc.
|
||||
|
||||
1. Install NDK r15c from https://developer.android.com/ndk/downloads/older_releases
|
||||
(yes, this sucks, but newer versions don't understand the `--deprecated-headers`
|
||||
argument required to build OpenSSL against a v21 toolchain).
|
||||
- Extract it, put it somewhere (`$HOME/.android-ndk-r15c` is a reasonable
|
||||
choice, but it doesn't matter), and set `NDK_HOME` to this location.
|
||||
|
||||
2. Install `rustup` from https://rustup.rs:
|
||||
- If you already have it, run `rustup update`
|
||||
- Run `rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android`
|
||||
- Run `rustup toolchain add beta` (TODO: this no longer appears necessary).
|
||||
|
||||
3. Ensure your clone of `mozilla/application-services` is up to date.
|
||||
|
||||
4. Setup your NDK toolchains.
|
||||
- Create a directory where we'll install the standalone toolchains.
|
||||
- `mkdir -p ~/.ndk-standalone-toolchains`
|
||||
- `export ANDROID_NDK_TOOLCHAIN_DIR=$HOME/.ndk-standalone-toolchains`
|
||||
- `cd path/to/application-services/libs`
|
||||
- `./setup_toolchains_local.sh $NDK_HOME`
|
||||
- Say yes if/when prompted.
|
||||
- When this is done, it should have set `$ANDROID_NDK_API_VERSION` (to 21),
|
||||
but you should add this to an rcfile as above.
|
||||
|
||||
5. Install or locate Java
|
||||
- Either install Java, or, if Android Studio is installed, you can probably find one
|
||||
installed in a `jre` directory under the Android Studio directory.
|
||||
- Set `JAVA_HOME` to this location and add it to your rc file.
|
||||
|
||||
6. Install or locate the Android SDKs
|
||||
- Install the Android SDKs. If Android Studio is involved, it may have already installed
|
||||
them somewhere - use the "SDK Manager" to identify this location.
|
||||
- Set `ANDROID_HOME` to this location and add it to your rc file.
|
||||
|
||||
7. Build openssl and sqlcipher
|
||||
- `cd path/to/application-services/libs` (Same dir you were just in for step 4)
|
||||
- `./build-all.sh android` (Go make some coffee or something, this will take
|
||||
some time as it has to compile sqlcipher and openssl for x86, arm, and arm64).
|
||||
- Note that if something goes wrong here
|
||||
- Check all environment variables mentions above are set and correct.
|
||||
- The following directories should exist, and point to standalone NDK
|
||||
toolchains `$ANDROID_NDK_TOOLCHAIN_DIR/{x86,arm,arm64}-$ANDROID_NDK_API_VERSION`.
|
||||
|
||||
## Building
|
||||
|
||||
Having done the above, the build process is the easy part! Again, ensure all
|
||||
environment variables mentioned above are in place.
|
||||
|
||||
1. Ensure your clone of application-services is up-to-date.
|
||||
|
||||
2. Ensure rust is up-to-date by running `rustup`
|
||||
|
||||
3. The builds are all performed by `./gradlew` and the general syntax used is
|
||||
`./gradlew project:task`
|
||||
|
||||
You can see a list of projects by executing `./gradlew projects` and a list
|
||||
of tasks by executing `./gradlew tasks`.
|
||||
|
||||
### Publishing the components to your local maven repository.
|
||||
|
||||
The easiest way to use the build is to have your Android project reference the component from your local maven repository - this is done by the `publishToMavenLocal` task - so:
|
||||
|
||||
./gradlew publishToMavenLocal
|
||||
|
||||
should work. Check your `~/.m2` directory (which is your local maven repo) for the components.
|
||||
|
||||
You can also publish single projects - eg:
|
||||
|
||||
./gradlew service-sync-places:publishToMavenLocal
|
||||
|
||||
For more information about using the local maven repo, see this [android components guide](https://mozilla-mobile.github.io/android-components/contributing/testing-components-inside-app)
|
||||
|
||||
### Other build types
|
||||
|
||||
If you just want the build artifacts, you probably want one of the `assemble` tasks - either
|
||||
`assembleDebug` or `assembleRelease`.
|
||||
|
||||
For example, to build a debug version of the places library, the command you
|
||||
want is `./gradlew places-library:assembleDebug`
|
||||
|
||||
After building, you should find the built artifact under the `target` directory,
|
||||
with sub-directories for each Android architecture. For example, after executing:
|
||||
|
||||
% ./gradlew places-library:assembleDebug
|
||||
|
||||
you will find:
|
||||
|
||||
target/aarch64-linux-android/release/libplaces_ffi.so
|
||||
target/i686-linux-android/release/libplaces_ffi.so
|
||||
target/armv7-linux-androideabi/release/libplaces_ffi.so
|
||||
|
||||
(You will probably notice that even though as used `assembleDebug`, the directory names are `release` - this may change in the future)
|
||||
|
||||
You should also find the .kt files for the project somewhere there and in the right directory structure if that turns out to be useful.
|
||||
|
||||
# Using Windows
|
||||
|
||||
It's currently tricky to get some of these builds working on Windows, primarily due to our use of `sqlcipher` and `openssl`. However, by using the Windows Subsystem for Linux, it is possible to get builds working, but still have them published to your "native" local maven cache so it's available for use by a "native" Android Studio.
|
||||
|
||||
As above, this document may be incomplete, so please edit or open PRs where necessary.
|
||||
|
||||
In general, you will follow the exact same process outlined above, with one or 2 unique twists.
|
||||
|
||||
## Setting up the build environment
|
||||
|
||||
You need to install most of the build tools in WSL. This means you end up with many tools installed twice - once in WSL and once in "native" Windows - but the only cost of that is disk-space.
|
||||
|
||||
You will need the following tools in WSL:
|
||||
|
||||
* unzip - `sudo apt install unzip`
|
||||
|
||||
* python - `sudo apt install python`
|
||||
|
||||
* java - you may already have it? try `java -version`. Java ended up causing me grief (stuck at 100% CPU doing nothing), but google pointed at one popular way of installing java:
|
||||
|
||||
```
|
||||
sudo add-apt-repository ppa:webupd8team/java
|
||||
sudo apt-get update
|
||||
sudo apt-get install oracle-java8-installer
|
||||
sudo apt install oracle-java8-set-default
|
||||
```
|
||||
|
||||
* tcl, used for sqlcipher builds - `sudo apt install tcl-dev`
|
||||
|
||||
* Android SDKs - this process is much the same as for normal Linux - roughly
|
||||
|
||||
* visit https://developer.android.com/studio/, at the bottom of the page locate the current SDKs for linux
|
||||
at time of writing, this is https://dl.google.com/android/repository/sdk-tools-linux-4333796.zip
|
||||
|
||||
```
|
||||
cd ~
|
||||
mkdir android-sdk
|
||||
cd android-sdk
|
||||
unzip {path-to.zip}
|
||||
export ANDROID_HOME=$HOME/android-sdk
|
||||
$ANDROID_HOME/tools/bin/sdkmanager "platforms;android-26"
|
||||
$ANDROID_HOME/tools/bin/sdkmanager --licenses
|
||||
```
|
||||
|
||||
(Note - it may be necessary to execute `$ANDROID_HOME/tools/bin/sdkmanager "build-tools;26.0.2" "platform-tools" "platforms;android-26" "tools"`, but may not! See also [this gist](https://gist.github.com/fdmnio/fd42caec2e5a7e93e12943376373b7d0) which google found for me and might have useful info.
|
||||
|
||||
* Follow all the other steps above - eg, you still need the NDK setup in WSL and all environment variables above set.
|
||||
|
||||
## Configure Maven
|
||||
|
||||
We now want to configure maven to use the native windows maven repository - then, when doing `./gradlew install` from WSL, it ends up in the Windows maven repo.
|
||||
|
||||
* Execute `sudo apt install maven` - this should have created a `~/.m2` folder as the WSL maven repository. In this directory, create a file `~/.m2/settings.xml` with the content:
|
||||
|
||||
```
|
||||
<settings>
|
||||
<localRepository>/mnt/c/Users/{username}/.m2/repository</localRepository>
|
||||
</settings>
|
||||
```
|
||||
|
||||
(obviously with {username} adjusted appropriately)
|
||||
|
||||
* Now you should be ready to roll - `./gradlew install` should complete and publish the components to your native maven repo!
|
||||
|
||||
\o/
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
id: working-with-reference-browser
|
||||
title: Development with the Reference Browser
|
||||
sidebar_label: Development with the Reference Browser
|
||||
---
|
||||
|
||||
## Working on unreleased application services code in android components or reference browser
|
||||
|
||||
This is a companion to the [equivalent instructions for the android-components repository](https://mozilla-mobile.github.io/android-components/contributing/testing-components-inside-app).
|
||||
|
||||
Modern Gradle supports [composite builds](https://docs.gradle.org/current/userguide/composite_builds.html), which allows to substitute on-disk projects for binary publications. Composite builds transparently accomplish what is usually a frustrating loop of:
|
||||
1. change library
|
||||
1. publishing library snapshot to the local Maven repository
|
||||
1. consume library snapshot in application
|
||||
|
||||
## Preparation
|
||||
|
||||
Let's assume that the (two or) three projects are siblings, like:
|
||||
```sh
|
||||
git clone https://github.com/mozilla/application-services
|
||||
git clone https://github.com/mozilla-mobile/android-components
|
||||
git clone https://github.com/mozilla-mobile/reference-browser
|
||||
```
|
||||
|
||||
## Substituting projects
|
||||
|
||||
In `android-components/settings.gradle`:
|
||||
```groovy
|
||||
includeBuild('../application-services') {
|
||||
dependencySubstitution {
|
||||
// As required.
|
||||
substitute module('org.mozilla.fxaclient:fxaclient') with project(':fxa-client-library')
|
||||
substitute module('org.mozilla.sync15:logins') with project(':logins-library')
|
||||
substitute module('org.mozilla.places:places') with project(':places-library')
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In `reference-browser/settings.gradle`:
|
||||
```groovy
|
||||
includeBuild('../android-components') {
|
||||
dependencySubstitution {
|
||||
// As required.
|
||||
substitute module('org.mozilla.components:service-firefox-accounts') with project(':service-firefox-accounts')
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Caveat
|
||||
|
||||
There's a big gotcha with library substitutions: the Gradle build computes lazily, and AARs don't include their transitive dependencies' JNI libraries. This means that in `android-components`, `./gradlew :service-sync-logins:assembleDebug` **does not** invoke `:logins-library:cargoBuild`, even though `:service-sync-logins` depends on the substitution for `:logins-library` and even if the inputs to Cargo have changed! It's the final consumer of the `:service-sync-logins` project (or publication) that will incorporate the JNI libraries.
|
||||
|
||||
In practice that means _you should always be targeting something that produces an APK_: a test, a sample module, or the Reference Browser itself. Then you should find that the `cargoBuild` tasks are invoked as you expect.
|
||||
|
||||
## Notes
|
||||
|
||||
1. Transitive substitutions (as shown above) work but require newer Gradle versions (4.10+).
|
||||
1. Android Studio happily imports substitutions (and transitive substitutions). However, the project list gets very large.
|
||||
|
|
@ -15,12 +15,20 @@
|
|||
"accounts/end-to-end-encryption": {
|
||||
"title": "End-to-end encryption"
|
||||
},
|
||||
"accounts/faq": {
|
||||
"title": "Frequently Asked Questions",
|
||||
"sidebar_label": "Frequently Asked Questions"
|
||||
},
|
||||
"accounts/fxa-client-android": {
|
||||
"title": "Android SDK"
|
||||
},
|
||||
"accounts/fxa-client-ios": {
|
||||
"title": "iOS SDK"
|
||||
},
|
||||
"accounts/local-development": {
|
||||
"title": "Local Development",
|
||||
"sidebar_label": "Local Development"
|
||||
},
|
||||
"accounts/metrics": {
|
||||
"title": "Metrics for Reliers",
|
||||
"sidebar_label": "Metrics for Reliers"
|
||||
|
|
@ -33,6 +41,10 @@
|
|||
"title": "About Firefox Accounts",
|
||||
"sidebar_label": "Welcome"
|
||||
},
|
||||
"applications/android-components": {
|
||||
"title": "Building the Android Components",
|
||||
"sidebar_label": "Building the Android Components"
|
||||
},
|
||||
"applications/signing-android-apps": {
|
||||
"title": "Signing Android Applications",
|
||||
"sidebar_label": "Signing Android Applications"
|
||||
|
|
@ -41,6 +53,10 @@
|
|||
"title": "Applications",
|
||||
"sidebar_label": "Intro"
|
||||
},
|
||||
"applications/working-with-reference-browser": {
|
||||
"title": "Development with the Reference Browser",
|
||||
"sidebar_label": "Development with the Reference Browser"
|
||||
},
|
||||
"doc1": {
|
||||
"title": "Docs",
|
||||
"sidebar_label": "Docs"
|
||||
|
|
|
|||
|
|
@ -8,8 +8,10 @@
|
|||
"Firefox Accounts": [
|
||||
"accounts/welcome",
|
||||
"accounts/project-details",
|
||||
"accounts/faq",
|
||||
"accounts/dev-process",
|
||||
"accounts/metrics"
|
||||
"accounts/metrics",
|
||||
"accounts/local-development"
|
||||
],
|
||||
"Mobile SDKs": [
|
||||
"accounts/fxa-client-ios",
|
||||
|
|
@ -23,7 +25,9 @@
|
|||
"applications": {
|
||||
"Applications": [
|
||||
"applications/welcome",
|
||||
"applications/signing-android-apps"
|
||||
"applications/signing-android-apps",
|
||||
"applications/android-components",
|
||||
"applications/working-with-reference-browser"
|
||||
]
|
||||
},
|
||||
"sync": {
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче