[docs] add some information about private mode

README.md

@@ -1,6 +1,12 @@
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+[![Apache 2.0 License][license-shield]][license-url]
+
 # Android SMS Gateway Server
 
-This server acts as the backend component of the Android SMS Gateway, facilitating the sending of SMS messages through connected Android devices. It includes a RESTful API for message management, integration with Firebase Cloud Messaging (FCM), and a database for persistent storage.
+This server acts as the backend component of the [Android SMS Gateway](https://github.com/capcom6/android-sms-gateway), facilitating the sending of SMS messages through connected Android devices. It includes a RESTful API for message management, integration with Firebase Cloud Messaging (FCM), and a database for persistent storage.
 
 ## Table of Contents
 
@@ -8,18 +14,17 @@ This server acts as the backend component of the Android SMS Gateway, facilitati
   - [Table of Contents](#table-of-contents)
   - [Features](#features)
   - [Prerequisites](#prerequisites)
-  - [Installation](#installation)
+  - [Quickstart](#quickstart)
-  - [Configuration](#configuration)
+  - [Work modes](#work-modes)
-  - [Running the Server](#running-the-server)
-    - [Running with Docker](#running-with-docker)
   - [Contributing](#contributing)
   - [License](#license)
 
 ## Features
 
 - Send SMS messages via a RESTful API.
-- Schedule and perform periodic tasks.
+- Get message status.
-- Integrate with Firebase Cloud Messaging for notifications.
+- Get the list of connected devices.
+- Public and private modes.
 
 ## Prerequisites
 
@@ -27,63 +32,30 @@ This server acts as the backend component of the Android SMS Gateway, facilitati
 - Docker and Docker Compose (for Docker-based setup)
 - A configured MySQL/MariaDB database
 
-## Installation
+## Quickstart
 
-To set up the server on your local machine for development and testing purposes, follow these steps:
+The easiest way to get started with the server is to use the Docker-based setup in Private Mode. In this mode device registration endpoint is protected, so no one can register a new device without knowing the token.
 
-1. Clone the repository to your local machine.
+1. Set up MySQL or MariaDB database.
-2. Install Go (version 1.21 or newer) if not already installed.
+2. Create config.yml, based on [config.example.yml](configs/config.example.yml). The most important sections are `database`, `http` and `gateway`. Environment variables can be used to override values in the config file.
-3. Navigate to the cloned directory and install dependencies:
+   1. In `gateway.mode` section set `private`.
+   2. In `gateway.private_token` section set the access token for device registration in private mode. This token must be set on devices with private mode active.
+3. Start the server in Docker: `docker run -p 3000:3000 -v ./config.yml:/app/config.yml capcom6/sms-gateway:latest`.
+4. Set up private mode on devices.
+5. Use started private server with the same API as the public server at [sms.capcom.me](https://sms.capcom.me).
 
-```bash
+See also [docker-composee.yml](deployments/docker-compose/docker-compose.yml) for Docker-based setup.
-make init
-```
 
-4. Build the server binary:
+## Work modes
 
-```bash
+The server has two work modes: public and private. The public mode allows anonymous device registration and used at [sms.capcom.me](https://sms.capcom.me). Private mode can be used to send sensitive messages and running server in local infrastructure.
-make build
-```
 
-## Configuration
+In most operations public and private modes are the same. But there are some differences:
 
-The server uses `yaml` for configuration with ability to override some values from environment variables. By default configuration is loaded from the `config.yml` file in the root directory. But path can be overridden with the `CONFIG_PATH` environment variable.
+- `POST /api/mobile/v1/device` endpoint is protected by API key in private mode. So it is not possible to register a new device on private server without knowing the token.
+- FCM notifications from private server are sent through `sms.capcom.me`. Notifications don't contain any sensitive data like phone numbers or message text.
 
-Below is a template for the `config.yml` file with environment variables in comments:
+See also [private mode discussion](https://github.com/capcom6/android-sms-gateway/issues/20).
-
-```yaml
-http:
-  listen: ":3000"   # HTTP__LISTEN
-database:
-  dialect: "mysql"  # DATABASE__DIALECT
-  host: "localhost" # DATABASE__HOST
-  port: 3306        # DATABASE__PORT
-  user: "sms"       # DATABASE__USER
-  password: "sms"   # DATABASE__PASSWORD
-  database: "sms"   # DATABASE__DATABASE
-  timezone: "UTC"   # DATABASE__TIMEZONE
-fcm:
-  credentials_json:  >
-    {
-    ...
-    }
-tasks:
-  hashing:
-    interval_seconds: 900
-```
-
-Replace the placeholder values with your actual configuration.
-
-## Running the Server
-
-### Running with Docker
-
-For convenience, a Docker-based setup is provided. Please refer to the Docker prerequisites above before proceeding.
-
-1. Prepare configuration file `config.yml`
-2. Pull the Docker image: `docker pull capcom6/sms-gateway`
-3. Apply database migrations: `docker run --rm -it -v ./config.yml:/app/config.yml capcom6/sms-gateway db:migrate`
-4. Start the server: `docker run -p 3000:3000 -v ./config.yml:/app/config.yml capcom6/sms-gateway`
 
 ## Contributing
 
@@ -100,4 +72,15 @@ Don't forget to give the project a star! Thanks again!
 
 ## License
 
-Distributed under the Apache-2.0 license. See [LICENSE](LICENSE) for more information.
+Distributed under the Apache-2.0 license. See [LICENSE](LICENSE) for more information.
+
+[contributors-shield]: https://img.shields.io/github/contributors/capcom6/sms-gateway.svg?style=for-the-badge
+[contributors-url]: https://github.com/capcom6/sms-gateway/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/capcom6/sms-gateway.svg?style=for-the-badge
+[forks-url]: https://github.com/capcom6/sms-gateway/network/members
+[stars-shield]: https://img.shields.io/github/stars/capcom6/sms-gateway.svg?style=for-the-badge
+[stars-url]: https://github.com/capcom6/sms-gateway/stargazers
+[issues-shield]: https://img.shields.io/github/issues/capcom6/sms-gateway.svg?style=for-the-badge
+[issues-url]: https://github.com/capcom6/sms-gateway/issues
+[license-shield]: https://img.shields.io/github/license/capcom6/sms-gateway.svg?style=for-the-badge
+[license-url]: https://github.com/capcom6/sms-gateway/blob/master/LICENSE

bitbucket-pipelines.yml

@@ -1,81 +0,0 @@
-image: atlassian/default-image:3
-
-definitions:
-  caches:
-    gomodules: ~/.cache/go-build
-  steps:
-    - step: &docker-lint
-        runs-on:
-          - self.hosted
-          - linux
-        name: Lint the Dockerfile
-        image: hadolint/hadolint:latest-debian
-        script:
-          - hadolint build/package/Dockerfile*
-    - step: &unit-tests
-        runs-on:
-          - self.hosted
-          - linux
-        name: Run unit tests
-        image: golang:1.20
-        caches:
-          - gomodules
-        script:
-          - echo '[url "ssh://git@bitbucket.org/"]' >> ~/.gitconfig
-          - echo '        insteadOf = https://bitbucket.org/' >> ~/.gitconfig
-          - go env -w GOPRIVATE="bitbucket.org/soft-c/*"
-          - go test ./...
-    - step: &build-docker
-        runs-on:
-          - self.hosted
-          - linux
-        name: Build and push Docker image
-        services:
-          - docker
-        caches:
-          - docker
-        script:
-          - docker version
-          - echo ${DOCKER_PASSWORD} | docker login ${DOCKER_CR} --username "$DOCKER_USERNAME" --password-stdin
-          - export SSH_PRV_KEY="$(cat /opt/atlassian/pipelines/agent/ssh/id_rsa)"
-          - chmod +x ./scripts/docker-build.sh && ./scripts/docker-build.sh
-    - step: &deploy
-        runs-on:
-          - self.hosted
-          - linux
-        name: Deploy to Docker Swarm
-        image: hashicorp/terraform:1.4
-        deployment: production
-        script:
-          - terraform -chdir=./deployments/docker-swarm-terraform init
-          - |
-            terraform -chdir=./deployments/docker-swarm-terraform apply -auto-approve -input=false \
-              -var "swarm-manager-host=${SWARM_MANAGER_HOST}" \
-              -var "registry-password=${DOCKER_PASSWORD}" \
-              -var "app-name=${APP_NAME}" \
-              -var "app-version=${BITBUCKET_TAG#v}" \
-              -var "app-host=${APP_HOST}" \
-              -var "app-config-b64=${APP_CONFIG_B64}" \
-              -var "app-env-json-b64=${APP_ENV_JSON_B64}"
-
-pipelines:
-  default:
-    - parallel:
-        - step: *docker-lint
-        - step: *unit-tests
-    - step: *build-docker
-  branches:
-    testing:
-      - parallel:
-          - step: *docker-lint
-          - step: *unit-tests
-      - step: *build-docker
-    master:
-      - parallel:
-          - step: *docker-lint
-          - step: *unit-tests
-      - step: *build-docker
-  tags:
-    v*:
-      - step: *build-docker
-      - step: *deploy

configs/config.example.yml

@@ -1,24 +1,20 @@
-gateway:
+gateway: # gateway config [GATEWAY__MODE]
-  mode: private
+  mode: private # gateway mode (public - allow anonymous device registration, private - protected registration) [GATEWAY__PRIVATE_TOKEN]
-  private_token: 123456789
+  private_token: 123456789 # access token for device registration in private mode
 http: # http server config
-  listen: 127.0.0.1:3000 # listen address
+  listen: 127.0.0.1:3000 # listen address [HTTP__LISTEN]
 database: # database
-  dialect: mysql # database dialect
+  dialect: mysql # database dialect (only mysql supported at the moment) [DATABASE__DIALECT]
-  host: localhost # database host
+  host: localhost # database host [DATABASE__HOST]
-  port: 3306 # database port
+  port: 3306 # database port [DATABASE__PORT]
-  user: root # database user
+  user: root # database user [DATABASE__USER]
-  password: root # database password
+  password: root # database password [DATABASE__PASSWORD]
-  database: sms # database name
+  database: sms # database name [DATABASE__DATABASE]
-  debug: true
+  timezone: UTC # database timezone (important for message TTL calculation) [DATABASE__TIMEZONE]
-  timezone: UTC
+fcm: # firebase cloud messaging config
-fcm:
+  credentials_json: "{}" # firebase credentials json (for public mode only) [FCM__CREDENTIALS_JSON]
-  credentials_json: >
+  timeout_seconds: 1 # push notification send timeout [FCM__DEBOUNCE_SECONDS]
-    {
+  debounce_seconds: 5 # push notification debounce (>= 5s) [FCM__TIMEOUT_SECONDS]
-    ...
+tasks: # tasks config
-    }
+  hashing: # hashing task (hashes processed messages for privacy purposes)
-  timeout_seconds: 1
+    interval_seconds: 15 # hashing interval in seconds [TASKS__HASHING__INTERVAL_SECONDS]
-  debounce_seconds: 1
-tasks:
-  hashing:
-    interval_seconds: 15

deployments/docker-swarm-terraform/providers.tf

@@ -10,9 +10,4 @@ terraform {
 provider "docker" {
   host     = var.swarm-manager-host
   ssh_opts = ["-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null"]
-  # registry_auth {
-  #   address  = "cr.selcloud.ru/soft-c"
-  #   username = "token"
-  #   password = var.registry-password
-  # }
 }

deployments/docker-swarm-terraform/variables.tf

@@ -4,12 +4,6 @@ variable "swarm-manager-host" {
   description = "Address of swarm manager"
 }
 
-# variable "registry-password" {
-#   type        = string
-#   description = "Password for Docker Images Registry"
-#   sensitive   = true
-# }
-
 variable "app-name" {
   type        = string
   description = "Name of app"

internal/config/config.go

@@ -8,11 +8,11 @@ const (
 )
 
 type Config struct {
-	Gateway  Gateway   `yaml:"gateway"`
+	Gateway  Gateway   `yaml:"gateway"`  // gateway config
-	HTTP     HTTP      `yaml:"http"`
+	HTTP     HTTP      `yaml:"http"`     // http server config
-	Database Database  `yaml:"database"`
+	Database Database  `yaml:"database"` // database config
-	FCM      FCMConfig `yaml:"fcm"`
+	FCM      FCMConfig `yaml:"fcm"`      // firebase cloud messaging config
-	Tasks    Tasks     `yaml:"tasks"`
+	Tasks    Tasks     `yaml:"tasks"`    // tasks config
 }
 
 type Gateway struct {
@@ -21,23 +21,23 @@ type Gateway struct {
 }
 
 type HTTP struct {
-	Listen string `yaml:"listen" envconfig:"HTTP__LISTEN"`
+	Listen string `yaml:"listen" envconfig:"HTTP__LISTEN"` // listen address
 }
 
 type Database struct {
-	Dialect  string `yaml:"dialect"  envconfig:"DATABASE__DIALECT"`
+	Dialect  string `yaml:"dialect"  envconfig:"DATABASE__DIALECT"`  // database dialect
-	Host     string `yaml:"host"     envconfig:"DATABASE__HOST"`
+	Host     string `yaml:"host"     envconfig:"DATABASE__HOST"`     // database host
-	Port     int    `yaml:"port"     envconfig:"DATABASE__PORT"`
+	Port     int    `yaml:"port"     envconfig:"DATABASE__PORT"`     // database port
-	User     string `yaml:"user"     envconfig:"DATABASE__USER"`
+	User     string `yaml:"user"     envconfig:"DATABASE__USER"`     // database user
-	Password string `yaml:"password" envconfig:"DATABASE__PASSWORD"`
+	Password string `yaml:"password" envconfig:"DATABASE__PASSWORD"` // database password
-	Database string `yaml:"database" envconfig:"DATABASE__DATABASE"`
+	Database string `yaml:"database" envconfig:"DATABASE__DATABASE"` // database name
-	Timezone string `yaml:"timezone" envconfig:"DATABASE__TIMEZONE"`
+	Timezone string `yaml:"timezone" envconfig:"DATABASE__TIMEZONE"` // database timezone
 }
 
 type FCMConfig struct {
-	CredentialsJSON string `yaml:"credentials_json"`
+	CredentialsJSON string `yaml:"credentials_json" envconfig:"FCM__CREDENTIALS_JSON"` // firebase credentials json (public mode only)
-	DebounceSeconds uint16 `yaml:"debounce_seconds"`
+	DebounceSeconds uint16 `yaml:"debounce_seconds" envconfig:"FCM__DEBOUNCE_SECONDS"` // push notification debounce (>= 5s)
-	TimeoutSeconds  uint16 `yaml:"timeout_seconds"`
+	TimeoutSeconds  uint16 `yaml:"timeout_seconds"  envconfig:"FCM__TIMEOUT_SECONDS"`  // push notification send timeout
 }
 
 type Tasks struct {
@@ -45,7 +45,7 @@ type Tasks struct {
 }
 
 type HashingTask struct {
-	IntervalSeconds uint16 `yaml:"interval_seconds"`
+	IntervalSeconds uint16 `yaml:"interval_seconds" envconfig:"TASKS__HASHING__INTERVAL_SECONDS"` // hashing interval in seconds
 }
 
 var defaultConfig = Config{

web/mkdocs/docs/getting-started.md

@@ -1,41 +0,0 @@
-# Getting Started
-
-First of all, you need to install the Android SMS Gateway app on your device as described in the [Installation](installation.md).
-
-The Android SMS Gateway can work in two modes: with a local server started on the device or with a cloud server at [sms.capcom.me](https://sms.capcom.me). The basic API is the same for both modes and is documented on the [Android SMS Gateway API Documentation](https://capcom6.github.io/android-sms-gateway/).
-
-## Local server
-
-<div align="center">
-    <img src="/assets/local-server.png" alt="Local server example settings">
-</div>
-
-This mode is recommended for sending messages from local network.
-
-1. Start the app on the device.
-2. Activate the `Local server` switch.
-3. Tap the `Offline` button at the bottom of the screen.
-4. In the `Local server` section, the local and public addresses of the device, along with the credentials for basic authentication, will be displayed. Please note that the public address is only usable if you have a "white" IP address and have correctly configured your firewall.
-5. Make a `curl` call from the local network using a command like the following, replacing `<username>`, `<password>`, and `<device_local_ip>` with the values obtained in step 4: 
-
-    ```
-    curl -X POST -u <username>:<password> -H "Content-Type: application/json" -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' http://<device_local_ip>:8080/message
-    ```
-
-## Cloud server
-
-<div align="center">
-    <img src="/assets/cloud-server.png" alt="Cloud server example settings">
-</div>
-
-If you need to send messages with dynamic or shared device IP, you can use the cloud server. The best part? No registration, email, or phone number is required to start using it.
-
-1. Start the app on the device.
-2. Activate the `Cloud server` switch.
-3. Tap the `Offline` button at the bottom of the screen.
-4. In the `Cloud server` section, the credentials for basic authentication will be displayed.
-5. Make a curl call using a command like the following, replacing `<username>` and `<password>` with the values obtained in step 4:
-
-    ```
-    curl -X POST -u <username>:<password> -H "Content-Type: application/json" -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' https://sms.capcom.me/api/3rdparty/v1/message
-    ```

web/mkdocs/docs/getting-started/index.md

@@ -0,0 +1,11 @@
+# Getting Started
+
+The Android SMS Gateway can operate in three distinct modes, all using the same API:
+
+1. [**Local Server**](./local-server.md): Operate entirely within your local network by running the server directly on your Android device. This is perfect for a quick setup and use where Internet access isn't necessary. For remote access, you may need to adjust your network settings and consider additional security measures.
+2. [**Public Cloud Server**](./public-cloud-server.md): Connect easily via the Internet using our public server at `sms.capcom.me`. Messages are routed through this server to your devices, which simplifies the setup without the need for network adjustments. This is suitable for non-sensitive data only — for more secure communication, please check out the [end-to-end encryption section](../privacy/encryption.md).
+3. [**Private Server**](./private-server.md): Deploy your own server instance and connect your Android devices to ensure maximum privacy. We won't have access to your message content, making this the preferred option for sensitive communication. However, it requires setting up and maintaining your own infrastructure, which includes a database and server application.
+
+For any of these modes, you'll first need to install the Android SMS Gateway app on your device as described in the [Installation](../installation.md) section.
+
+For more information on how to use the API, please refer to the [API](../api.md) section.

web/mkdocs/docs/getting-started/local-server.md

@@ -0,0 +1,19 @@
+# Getting Started
+
+## Local Server
+
+<div align="center">
+    <img src="/assets/local-server.png" alt="Example settings for Local Server mode">
+</div>
+
+This mode is ideal for sending messages from a local network.
+
+1. Launch the app on your device.
+2. Toggle the `Local Server` switch to the "on" position.
+3. Tap the `Offline` button located at the bottom of the screen to activate the server.
+4. The `Local Server` section will display your device's local and public IP addresses, as well as the credentials for basic authentication. Please note that the public IP address is only accessible if you have a public (also known as "white") IP and your firewall is configured appropriately.
+5. To send a message from within the local network, execute a `curl` command like the following. Be sure to replace `<username>`, `<password>`, and `<device_local_ip>` with the actual values provided in the previous step:
+
+    ```sh
+    curl -X POST -u <username>:<password> -H "Content-Type: application/json" -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' http://<device_local_ip>:8080/message
+    ```

web/mkdocs/docs/getting-started/private-server.md

@@ -0,0 +1,32 @@
+# Getting Started
+
+## Private Server
+
+<div align="center">
+    <img src="/assets/private-server.png" alt="Example settings for Private Server mode">
+</div>
+
+To enhance privacy, you can host a private server within your own infrastructure, ensuring that your messages reside only on devices you control. The only required external network connection is for sending push notifications through the public server at `sms.capcom.me`. This architecture eliminates the need to set up Firebase Cloud Messaging (FCM) and rebuild the Android app, though it does require some technical expertise.
+
+### Prerequisites
+
+- A MySQL or MariaDB database server with an empty database and a user granted full access to that database.
+- A VPS (Virtual Private Server) running Linux with Docker installed.
+- A reverse proxy with an SSL certificate and HTTPS enabled.
+
+### Run the Server
+
+1. Create a `config.yml` file based on the [config.example.yml](https://github.com/capcom6/sms-gateway/blob/master/configs/config.example.yml). The critical sections to configure are `database`, `http`, and `gateway`. Environment variables can be used to override values in the config file.
+   - In the `gateway.mode` section, set the value to `private`.
+   - In the `gateway.private_token` section, specify the access token for device registration in private mode. This token must also be set on devices operating in private mode.
+2. Launch the server in Docker with the following command: 
+   ```sh
+   docker run -p 3000:3000 -v $(pwd)/config.yml:/app/config.yml capcom6/sms-gateway:latest
+   ```
+3. Set up your reverse proxy, configure SSL, and adjust your firewall to allow access to the server from the Internet.
+
+For additional details, refer to the server's [README.md](https://github.com/capcom6/sms-gateway/blob/master/README.md).
+
+### Configure Android App
+
+To be continued...

web/mkdocs/docs/getting-started/public-cloud-server.md

@@ -0,0 +1,20 @@
+# Getting Started
+
+## Cloud Server
+
+<div align="center">
+    <img src="/assets/cloud-server.png" alt="Example settings for Cloud Server mode">
+</div>
+
+Use the cloud server mode when dealing with dynamic or shared device IP addresses. The best part? No registration, email, or phone number is required to start using it.
+
+1. Launch the app on your device.
+2. Toggle the `Cloud Server` switch to the "on" position.
+3. Tap the `Online` button located at the bottom of the screen to connect to the cloud server.
+4. In the `Cloud Server` section, the credentials for basic authentication will be displayed.
+5. To send a message via the cloud server, perform a `curl` request with a command similar to the following, substituting `<username>` and `<password>` with the actual values obtained in step 4:
+
+    ```sh
+    curl -X POST -u <username>:<password> -H "Content-Type: application/json" -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' https://sms.capcom.me/api/3rdparty/v1/message
+    ```
+    

web/mkdocs/docs/index.md

@@ -17,6 +17,9 @@ Android SMS Gateway turns your Android smartphone into an SMS gateway. It's a li
 - **Starts at boot:** The application starts running as soon as your device boots up.
 - **Multiple SIM cards:** The application supports multiple SIM cards.
 - **Multipart messages:** The application supports sending long messages with auto-partitioning.
+- **End-to-end encryption:** The application supports end-to-end encryption by encrypting message text and recipients' phone numbers before sending them to the API and decrypting them on the device.
+- **Messages expiration:** The application supports setting messages' expiration time. The messages will not be sent if they are expired.
+- **Random delay between sending messages:** To avoid mobile operator restrictions.
 
 ## Ideal For
 
@@ -34,7 +37,7 @@ The project is currently in the MVP stage. We're actively working on adding more
 
 Getting started with Android SMS Gateway is easy and straightforward. No registration, email, or phone number is required to create an account and start using the app. 
 
-Check out our [Getting Started Guide](getting-started.md) to learn how to install and use Android SMS Gateway.
+Check out our [Getting Started Guide](getting-started/index.md) to learn how to install and use Android SMS Gateway.
 
 ## Contributing
 

web/mkdocs/mkdocs.yml

@@ -29,7 +29,11 @@ theme:
 nav:
   - Home: index.md
   - Installation: installation.md
-  - Getting Started: getting-started.md
+  - Getting Started:
+      - Overview: getting-started/index.md
+      - Local Server: getting-started/local-server.md
+      - Public Cloud Server: getting-started/public-cloud-server.md
+      - Private Server: getting-started/private-server.md
   - API: api.md
   - Pricing: pricing.md
   - Privacy: