Improve documentation

.github/workflows/build.yaml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - master
+      - beta
       - dev
       - http-rest
   pull_request:
@@ -31,7 +32,12 @@ jobs:
           echo "::set-output name=version::$(cat VERSION)"
       - name: Set repo
         id: repo
-        run: if [[ $GITHUB_REF == "refs/heads/master" ]]; then echo "::set-output name=repo::${DOCKER_REPO}"; else echo "::set-output name=repo::${DOCKER_REPO_DEV}"; fi
+        run: |
+          if [[ $GITHUB_REF == "refs/heads/master" || $GITHUB_REF == "refs/heads/beta" ]]; then
+            echo "::set-output name=repo::${DOCKER_REPO}"
+          else
+            echo "::set-output name=repo::${DOCKER_REPO_DEV}"
+          fi
       - name: Docker meta
         id: docker_meta
         uses: crazy-max/ghaction-docker-meta@v1
@@ -64,13 +70,13 @@ jobs:
           sarif_file: ${{ steps.scan.outputs.sarif }}
       - name: Login to DockerHub
         uses: docker/login-action@v1
-        if: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/master' }}
+        if: ${{ github.event_name != 'pull_request' && steps.repo.outputs.repo == ${DOCKER_REPO} }}
         with:
           username: ${{ secrets.REGISTRY_USERNAME }}
           password: ${{ secrets.REGISTRY_PASSWORD }}
       - name: Login to GitHub Container Registry
         uses: docker/login-action@v1
-        if: ${{ github.event_name != 'pull_request' && github.ref != 'refs/heads/master' }}
+        if: ${{ github.event_name != 'pull_request' && steps.repo.outputs.repo == ${DOCKER_REPO_DEV} }}
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
@@ -83,6 +89,5 @@ jobs:
           tags: |
             ${{ steps.repo.outputs.repo }}:beta
             ${{ steps.repo.outputs.repo }}:${{ steps.version.outputs.version }}
-            ${{ steps.repo.outputs.repo }}:${{ steps.version.outputs.bridge_version }}-${{ steps.version.outputs.version }}
           labels: ${{ steps.docker_meta.outputs.labels }}
           push: ${{ github.event_name != 'pull_request' }}

README.md

@@ -12,11 +12,82 @@ Docker Hub: [https://hub.docker.com/r/shenxn/protonmail-bridge](https://hub.dock
 
 GitHub: [https://github.com/shenxn/protonmail-bridge-docker](https://github.com/shenxn/protonmail-bridge-docker)
 
-## ARM Support
+## ProtonMail Bridge Docker 2.0 Announcement
 
-We now support ARM devices (`arm64` and `arm/v7`)! Use the images tagged with `build`. See next section for details.
+ProtonMail Bridge Docker 2.0 uses a completely different approach that makes the whole container much easier to use. First of all, it now supports setting up with environmental variables only. No longer messing with terminal commands. Secondly, it now provides a easy way to interact with the bridge, include getting account information, adding, and removing accounts, all after the first initialization. This version is now in beta. Feel free to test it by using the `beta` tag (`shenxn/protonmail-bridge:beta`).
 
-## Tags
+### Environmental Variables
+
+name | default | description
+ -- | -- | --
+`PROTON_USERNAME` | | Username of your Proton account.
+`PROTON_PASSWORD` | | Password of your Proton account.
+`PROTON_2FA` | | Two-factor authentication code of your Proton account. Only needed if you have two factor authentication enabled.
+`PROTON_MAILBOX_PASSWORD` | | Mailbox password of your Proton account. Only needed if you have two-password mode enabled.
+`PROTON_PRINT_ACCOUNT_INFO` | `true` | Whether to print the local connection information (username, password, ports, security, etc.) on successful auto logins. Set to `false` to turn it off.
+`PROTON_IMAP_PORT` | `25` | IMAP port of the bridge.
+`PROTON_SMTP_PORT` | `143` | SMTP port of the bridge.
+`PROTON_SMTP_SECURITY` | `STARTTLS` | Connection security of SMTP. Can be set to `STARTTLS` or `SSL`.
+`PROTON_MANAGEMENT_PORT` | `1080` | Port of the management HTTP server.
+`PROTON_ALLOW_PROXY` | `true` | Allow or disallow the Bridge client to securely connect to Proton via a third party when it is being blocked.
+`PROTON_UID` | `1001` | UID of the user to run the bridge.
+`PROTON_GID` | `1001` | GID of the group to run the bridge.
+
+### Data Volume
+
+All data are stored under `/protonmail/data`.
+
+### Auto Login
+
+2.0 comes with auto login, a highly demanded feature. By set `PROTON_USERNAME`, `PROTON_PASSWORD`, `PROTON_2FA`, and `PROTON_MAILBOX_PASSWORD`, the container will automatically add your account to the bridge and print local connection info to the log. Note:
+- The auto login feature only kicks in when the bridge has zero account added. If there is at least one account, auto login will be skipped. Changing the environmental variables will neither add another account to the bridge nor replace the account with the new one. To do so, use [CLI](#cli).
+- Two factor authentication codes time out quickly (in 30 seconds). It is highly possible that the code is already expired at the time login take place. To help with that, you can try pull the image first before setting it. You can also wait for a new code so that the container will have full 30 seconds to boot up. If non of them works, try manual login with [CLI](#cli).
+- If your container logs can be accessed by someone else, it is recommended to turn of the account info printing by set `PROTON_PRINT_ACCOUNT_INFO` to `false`. Then you can use [CLI](#cli) to fetch the account info.
+
+### CLI
+
+2.0 comes with a CLI to easily interact with the bridge. There is no need to modify the entrypoint, manually kill any process, or restart the container when you are done. Everything you need is to `exec` into the container and run `cli.sh`. With that, you can add, remove, list accounts and print account info. Changing the address mode of an account is currently not supported. To do so, simply delete the account and add it back again. Example:
+```
+➜ docker exec -it protonmail cli.sh
+CLI to interacte with Proton Bridge HTTP REST interface
+Available commands:
+ login:            Calls up the login procedure to add or connect accounts.
+ delete <account>: Remove the account from keychain. You can use index or account name as the parameter.
+ list:             Print list of your accounts.
+ info <account>:   Print account configuration. You can use index or account name as the parameter.
+ help:             Print help messages.
+ exit:             Exit the CLI
+
+>> info bob
+Configuration for bob@proton.me
+IMAP port: 143
+IMAP security: STARTTLS
+SMTP port: 25
+SMTP security: STARTTLS
+Username:  bob@proton.me
+Password:  xxxxxxxxxxxxxxxxxxxxxx
+
+>> exit
+```
+
+### Migrate from old version
+
+To migrate, you just need to change the mount path from `/root` to `/protonmail/data` and the container will do the rest of the work. Note that this is a one way trip. There is no way to get back to the old version. You'll need to set up everything again from scratch to go back. Also, any bridge preferences (e.g. whether to use a proxy) will not be migrated. You'll need to set them again with the environmental variables. Not all preferences are supported yet. Feel free to open an issue or PR for options you want to change. If anything goes sideways, it can be caused by problematic migrating steps. You can try to clear your volume and start everything from the scratch.
+
+## Supported architectures
+
+architecture | status | note
+ -- | --
+`amd64` | supported |
+`arm64/v8` | supported |
+`arm/v7` | supported | 32-bit platforms are no longer officially supported by Proton. Thanks to blumberg for the workaround [#40](https://github.com/shenxn/protonmail-bridge-docker/pull/40)
+`riscv64` | WIP | Check progress at [#54](https://github.com/shenxn/protonmail-bridge-docker/pull/54)
+
+## Legacy Documentation
+
+This section contains information for the old version. They are kept here for reference and will be removed once 2.0 graduates from beta.
+
+### Tags
 
 There are two types of images.
  - `deb`: Images based on the official [.deb release](https://protonmail.com/bridge/install). It only supports the `amd64` architecture.
@@ -29,7 +100,7 @@ tag | description
 `build` | latest `build` image
 `[version]-build` | `build` images
 
-## Initialization
+### Initialization
 
 To initialize and add account to the bridge, run the following command.
 
@@ -39,7 +110,7 @@ docker run --rm -it -v protonmail:/root shenxn/protonmail-bridge init
 
 Wait for the bridge to startup, use `login` command and follow the instructions to add your account into the bridge. Then use `info` to see the configuration information (username and password). After that, use `exit` to exit the bridge. You may need `CTRL+C` to exit the docker entirely.
 
-## Run
+### Run
 
 To run the container, use the following command.
 
@@ -47,13 +118,13 @@ To run the container, use the following command.
 docker run -d --name=protonmail-bridge -v protonmail:/root -p 1025:25/tcp -p 1143:143/tcp --restart=unless-stopped shenxn/protonmail-bridge
 ```
 
-## Kubernetes
+### Kubernetes
 
 If you want to run this image in a Kubernetes environment. You can use the [Helm](https://helm.sh/) chart (https://github.com/k8s-at-home/charts/tree/master/charts/stable/protonmail-bridge) created by [@Eagleman7](https://github.com/Eagleman7). More details can be found in [#23](https://github.com/shenxn/protonmail-bridge-docker/issues/23).
 
 If you don't want to use Helm, you can also reference to the guide ([#6](https://github.com/shenxn/protonmail-bridge-docker/issues/6)) written by [@ghudgins](https://github.com/ghudgins).
 
-## Security
+### Security
 
 Please be aware that running the command above will expose your bridge to the network. Remember to use firewall if you are going to run this in an untrusted network or on a machine that has public IP address. You can also use the following command to publish the port to only localhost, which is the same behavior as the official bridge package.
 
@@ -63,15 +134,15 @@ docker run -d --name=protonmail-bridge -v protonmail:/root -p 127.0.0.1:1025:25/
 
 Besides, you can publish only port 25 (SMTP) if you don't need to receive any email (e.g. as a email notification service).
 
-## Compatibility
+### Compatibility
 
 The bridge currently only supports some of the email clients. More details can be found on the official website. I've tested this on a Synology DiskStation and it runs well. However, you may need ssh onto it to run the interactive docker command to add your account. The main reason of using this instead of environment variables is that it seems to be the best way to support two-factor authentication.
 
-## Bridge CLI Guide
+### Bridge CLI Guide
 
 The initialization step exposes the bridge CLI so you can do things like switch between combined and split mode, change proxy, etc. The [official guide](https://protonmail.com/support/knowledge-base/bridge-cli-guide/) gives more information on to use the CLI.
 
-## Build
+### Build
 
 For anyone who want to build this container on your own (for development or security concerns), here is the guide to do so. First, you need to `cd` into the directory (`deb` or `build`, depending on which type of image you want). Then just run the docker build command
 ```

VERSION

@@ -1 +1 @@
-2.0-beta
+2.0.0-beta

build.sh

@@ -13,6 +13,8 @@ cp -r /build/http_rest_frontend/cli internal/frontend/
 
 # Build
 if ! make build-nogui ; then
+	dpkg --print-architecture
+
 	# If build fails it's probably because it is a 32bit
 	# system and there was a overflow error on the parser
 	# This is a workaround for this problem found at:

http_rest_frontend/cli/frontend.go

@@ -104,7 +104,7 @@ func (f *frontendCLI) loginWithEnv() {
 		return
 	}
 	logrus.Infof("Account %s was added successfully.\n", user.Username())
-	if strings.ToLower(os.Getenv("PROTON_PRINT_ACCOUNT_INFO")) != "off" {
+	if strings.ToLower(os.Getenv("PROTON_PRINT_ACCOUNT_INFO")) != "false" {
 		f.printAccountInfo(os.Stdout, user)
 	}
 }

run_protonmail_bridge.sh

@@ -61,10 +61,12 @@ cat <<EOF > ${PROTON_CONFIG_PATH}/bridge/prefs.json
 }
 EOF
 
+export PROTON_SMTP_PORT=${PROTON_SMTP_PORT:-25}
+export PROTON_IMAP_PORT=${PROTON_IMAP_PORT:=143}
 # socat will make the conn appear to come from 127.0.0.1
 # ProtonMail Bridge currently expects that.
 # It also allows us to bind to the real ports :)
-socat TCP-LISTEN:${PROTON_SMTP_PORT:=25},fork TCP:127.0.0.1:1025 &
+socat TCP-LISTEN:${PROTON_SMTP_PORT},fork TCP:127.0.0.1:1025 &
-socat TCP-LISTEN:${PROTON_IMAP_PORT:=143},fork TCP:127.0.0.1:1143 &
+socat TCP-LISTEN:${PROTON_IMAP_PORT},fork TCP:127.0.0.1:1143 &
 
 exec proton-bridge --cli "$@"