Deploy and backup Android applications from F-Droid repository in computer side
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Xu Fasheng f5ae95bf37 readme: Update quick start 1 month ago
completion Rename project to deplaydroid 1 month ago
example example: Add deploy-nethunter 2 months ago
include adb_utils: Add adb_remount-system-rw and adb_remount-system-ro subcmd 2 months ago
LICENSE Add README, LICENSE 10 months ago
README.org readme: Update quick start 1 month ago
deplaydroid Fix global variable order 1 month ago
gen_code.sh Rename project to deplaydroid 1 month ago

README.org

Description: Deploy and backup Android applications from F-Droid repository in computer side.

Keywords: shell, android, fdroid, package-manager, deploy, backup, root, titanium-backup

Features

  • Support download and install Android application from F-Droid repository

  • Support upgrade applications to latest version in device if possible

  • Support shell completion

  • Support multiple users

  • Support backup and restore applications

  • Support backup special data, such as accounts, WiFi access-points

  • Support increment backup, the data files that timestamp not changed will be ignored

  • Support create profile file for different device

  • Provide methods to encrypt user data

  • Try to fix compatibility issue when restore applications to different Android version

  • Works fine for Android 4.0+ (API level 14+). And the older versions should works, too, but need more testing work

Requirement

Command dependents in computer side:

  • bash >=4.0

  • curl

  • xmlstarlet

  • sha1sum

  • sha256sum

  • tar

  • gzip

  • adb

  • openssl (only need for –password option)

And in Android side:

  • sha1sum

  • find

  • tar

  • gzip

  • gunzip (if missing just install busybox)

  • Enable debug mode

  • Root permission in adb shell, either adb root works or su command exists will be fine

  • Enough free space in device temporary directory (default is /data/local/tmp, and could special it with argument --device-tmpdir)

Quick start

# download deplaydroid
git clone https://gitea.com/fasheng/deplaydroid.git
cd deplaydroid

# enable command completion for bash
source <(./deplaydroid complete --bash)

# install packages
./deplaydroid update
./deplaydroid install org.fdroid.fdroid com.nextcloud.client

# upgrade packages
./deplaydroid upgrade

# deploy microg packages
./deplaydroid install --profile example/deploy-microg.sh

# backup packages
./deplaydroid backup org.fdroid.fdroid com.nextcloud.client

# restore packages
./deplaydroid restore org.fdroid.fdroid com.nextcloud.client

Usage

  1. Enable command completion

    • for bash

      source <(deplaydroid complete --bash)
      
    • for fish

      source <(deplaydroid complete --fish | psub)
      
  2. Update F-Droid repository index.xml file before operations

    deplaydroid update
    
  3. List packages

    • List all packages, could use --cat, --desc, --ver to show category, description and available versions

      deplaydroid list
      deplaydroid list --cat --desc --ver
      
    • List packages with matched keyword, the keyword support awk regexp syntax. And if use --cat, --desc, --ver, will search text in the related fields

      deplaydroid list fdroid
      deplaydroid list --cat --desc --ver fdroid
      
    • List packages in category "System"

      deplaydroid list --cat System
      
    • List packages with special package names

      deplaydroid list --pkg org.fdroid.fdroid org.fdroid.fdroid.privileged
      
    • List packages in special repository

      deplaydroid list --repo fdroid
      
    • Show package suggest version, the result will be different if different adb device connected

      deplaydroid list --sug --pkg org.fdroid.fdroid com.jereksel.libresubstratum
      
  4. Download and install package to device

    • Install the suggest latest stable version

      deplaydroid install org.fdroid.fdroid
      
    • Install the suggest version, include unstable version

      deplaydroid install --allow-unstable org.fdroid.fdroid
      
    • Install special version

      deplaydroid install org.fdroid.fdroid=1007051
      
    • Install to special users

      deplaydroid adb list-users
      deplaydroid install --user 0 --user 10 org.fdroid.fdroid
      
  5. Uninstall package from device

    deplaydroid uninstall --user cur org.fdroid.fdroid
    
  6. Upgrade packages

    • List all upgrade-able packages

      deplaydroid upgrade --list
      
    • Upgrade all packages if possible

      deplaydroid upgrade
      
  7. Deploy and cleanup packages in profile

    • deploy microg packages

      deplaydroid install --profile example/deploy-microg.sh
      deplaydroid uninstall --profile example/deploy-microg.sh
      
    • deploy nextcloud packages

      deplaydroid install --profile example/deploy-nextcloud.sh
      deplaydroid uninstall --profile example/deploy-nextcloud.sh
      
    • backup and cleanup useless services in Samsung devices

      deplaydroid backup --profile ./example/cleanup-samsung.sh
      deplaydroid uninstall --profile ./example/cleanup-samsung.sh
      
  8. Backup & Restore packages

    1. Ensure root permission for adb shell works firstly, there are two methods:

      1. su coommand works

        adb shell su -c "id -u -r"
        
      2. adb root works

        adb root
        adb shell "id -u -r"
        
    2. Backup apps and restore later

      deplaydroid backup --user cur com.pkg1.name com.pkg2.name
      deplaydroid restore --user cur com.pkg1.name com.pkg2.name
      
    3. Backup or restore with the appinfo.sh file

      deplaydroid backup --type 'app+data' --user 0 ./data/default/user_0/com.pkg.name/appinfo.sh
      deplaydroid restore --type 'app+data' --user 10 ./data/default/user_0/com.pkg.name/appinfo.sh
      
    4. Clone apps to another device or user, will create user automatically

      deplaydroid backup --user cur com.pkg.name
      deplaydroid restore --user 10 --user 11 ./data/default/user_0/com.pkg.name/appinfo.sh
      
    5. Backup special user data, such as accounts and saved WiFi access points

      deplaydroid backup @user.accounts @wifi
      
    6. Create backup profile, so flashing roms work will be easy

      deplaydroid new-backup --3rd-app --3rd-data --freq-data --spec-data --profile test.sh
      deplaydroid backup --profile test.sh
      deplaydroid restore --profile test.sh
      
    7. Encrypt the user data

      1. Use --password argument set the archive password, if value is "-", will read password from input

        deplaydroid backup --password - com.pkg.name
        deplaydroid restore --password - com.pkg.name
        
      2. Use encfs or similar tools encrypt the full data directory

        encfs .data data
        
  9. Special Android device with $ANDROID_SERIAL, useful when multiple devices connected

    env ANDROID_SERIAL=xxxx deplaydroid <commands>
    

Configuration

Just customize F-Droid repository sources and other variables in ~/.config/deplaydroid/config.sh, here is an example:

fdroid_opt_cache_dir="${HOME}/.cache/deplaydroid"
fdroid_opt_download_cmd="wget -c '%s'"
adb_opt_device_tmpdir='/data/local/tmp'
repos=(
  ["fdroid"]="https://f-droid.org/repo"
  ["retroarch"]="https://fdroid.libretro.com/repo"
  ["microg"]="https://microg.org/fdroid/repo"
)

Backup directory structure

├── profile.sh
├── app
│   ├── com.pkg.name-1.0-10.apk
└── data
    └── profile-name
        └── user_0
        │   ├── com.pkg.name
        │   │   ├── com.pkg.name.tar.gz
        │   │   └── appinfo.sh
        │   └── @user.wallpaper
        │       ├── appinfo.sh
        │       └── @user.wallpaper.tar.gz
        └── user_system
            ├── @bluetooth
            │   ├── @bluetooth.tar.gz
            │   └── appinfo.sh
            └── @wifi
                ├── appinfo.sh
                └── @wifi.tar.gz
deploy/backup profile.sh example
name='test'

# useful for backup command
appdir='./app'
datadir='./data/default'
android_version='6.0.1'
android_api_level=23

# useful for install command
fdroid_repos=(
  ["fdroid"]="https://f-droid.org/repo"
  ["microg"]="https://microg.org/fdroid/repo"
)
fdroid_opt_allow_unstable=

users=(system 0)

user_system_name=''
user_system_datadir="${datadir}/user_system"
user_system_packages=(
  # spec system data
  '@datausage'
  '@bluetooth'
  '@wifi'
  # system apps
  'com.google.android.gms:app:repo=microg;version_code=19420020;install_dir=/system/priv-app' # microG Services Core
)

user_0_name='Owner'
user_0_datadir="${datadir}/user_0"
user_0_packages=(
  # spec user data
  '@user.accounts'
  '@user.wallpaper'
  # system apps data
  'com.google.android.gms:data' # microG Services Core
  # 3rd apps
  'org.fdroid.fdroid:app+data'  # F-Droid
)
appinfo.sh example
id='org.fdroid.fdroid'
display_name='F-Droid'
version_name='1.6'
version_code='1006050'
android_version='6.0.1'
android_api_level='23'
is_system=''
is_encrypted=''
install_dir='/vendor/app'
data_timestamp='1552435308'

Full help message

deplaydroid  [Global Options] [args] [-h|--help]

Global Options:
    PKG, package name, such as org.fdroid.fdroid
    VERPKG, package name that could special the version code, such as org.fdroid.fdroid, org.fdroid.fdroid=1007051
    DEVPKG, installed package name in android device
    BACKPKG, installed package name in android device or special data which defined in $backup_spec_apps
      such as org.fdroid.fdroid, @wifi
    -c, --config, special config file [default: '~/.config/deplaydroid/config.sh']
    --cache-dir, special cache directory [default: '~/.cache/deplaydroid']
    -u, --user, special user id, could set multiple times
      if value is 'cur' or 'current' will action for current user
      if not specialized will action for all users
    --no-color, remove colorful message
    -v, --verbose, show verbose message
    -h, --help, show help message

    ADB function options:
        --device-tmpdir, special tmpdir in android [default: '/data/local/tmp']
        --root-type, could be 'auto', 'su' or 'adb-root' (default: 'auto')

    Backup command options:
        --appdir, special application direcotory [default: './app']
        --archive-side, create and extract archive in device or host [default: 'auto']
          could be 'auto', 'device' and 'host'. Archive in device will save lots of time
          for the huge data, but 'tar' and 'gzip' commands requires in device.
        --name, profile name [default: 'default' or profile filename]
        -p, --profile, target profile file
        --password, encrypt the user data archive with password
          if set to '-', will read from input
        --type, could be 'app', 'data' and 'app+data' (default: 'app+data')

    F-Droid command options:
        --allow-unstable, allow unstable package release
        -r, --repo, special repo, could set multiple times

Commands:
    adb 
        run adb wrapped commands, helps for debug work
    backup [--name name] [--password pwd] [-u|--user id] [--type type] [--appdir dir] [--device-tmpdir dir] [--archive-side value] <-p|--profile file.sh|BACKPKG|appinfo.sh..>
        backup android application and user data
    check-backup [--fix] [--clean] [--copy-to dir] [--move-to dir] [--appdir dir] [dir|-p|--profile file.sh]
        check backup app and data in special directory or profile
        --fix, fix incompatible issues if possible
        --clean, remove apk files that lost reference, only works without --profile
        --copy-to, copy the related app and data to another directory, only works with --profile
        --move-to, move the related app and data to another directory, only works with --profile
    complete [--bash|--fish]
        generate command completion code for shell
        --bash, show completion code for bash
        --fish, show completion code for fish
    download [-r|--repo name] [--allow-unstable] [--force-download] 
        download packages
        if already exists, check the hash
        --force-download, always download package even through file exists
    install [-r|--repo name] [-u|--user id] [--allow-unstable] [--allow-downgrade] [--sys] [--install-dir dir] <-p|--profile file.sh|VERPKG|APKFILE..>
        download and install packages
        --sys, install as system package
        --install-dir, install system package to special directory [default: '/system/app']
        --allow-downgrade, allow downgrade package
    list [-r|--repo name] [--cat] [--desc] [--ver] [--sug] [--only-ver] [--allow-unstable] [--pkg] [keyword|PKG..]
        list matched packages
        --pkg, use package name instead keyword
          the keyword support awk regexp syntax
        --cat, show and match for category
        --desc, show and match for package description
        --ver, show all package version details
        --sug, show suggest version
          only works for keyword or PKG specialized
        --only-ver, show package versions only
    new-backup [--3rd-app] [--3rd-data] [--sys-app] [--sys-data] [--freq-app] [--freq-data] [--spec-data] [--name name] [-u|--user id] [--appdir dir] [--device-tmpdir dir] <-p|--profile file.sh>
        new backup profile for current devices
        --3rd-app, backup 3rd application
        --3rd-data, backup 3rd application data
        --sys-app, backup system application
        --sys-data, backup system application data
        --freq-app, backup frequently used application which defined in $backup_freq_apps
          such as contacts, call logs
          (conflict with --sys-app and --sys-data)
        --freq-data, backup frequently used application data
        --spec-data, backup special data which defined in $backup_spec_apps
          such as user accounts, saved wifi access points
    restore [--name name] [-u|--user id] [--type type] [--wait-sys-app seconds] [--default-install-dir] [--appdir dir] [--device-tmpdir dir] [--archive-side value] <-p|--profile file.sh|BACKPKG|appinfo.sh..>
        restore android application and user data, for multiple users, will create user if need
        --wait-sys-app, wait for new installed system app ready [default: 3]
        --default-install-dir, install app to /data/app or /system/app instead of the defined install_dir in appinfo.sh
    uninstall [-u|--user id] [--keep-data] <-p|--profile file.sh|DEVPKG..>
        uninstall packages
        --keep-data, keep the data and cache directories after removal
    update [-r|--repo name]
        download fdroid repo index.xml file to cache direcotry
    upgrade [-r|--repo name] [-u|--user id] [-l|--list] [DEVPKG..]
        upgrade packages
        if no package specialized, will upgrade all packages
        -l, --list, only list all upgradeable packages

Adb Wrapped Commands:
    check-online
    check-root
    chown-recursive  
    clear-package  [user-id] (user-id default: all users)
    create-user  
    ensure-user-exists  
    fix-package-datadir-permission  [user-id] (user-id default: current user)
    fix-selinux-permission 
    get-android-abi-list
    get-android-api-level
    get-android-version
    get-current-user
    get-file-timestamp 
    get-package-datadir  [user-id] [apilevel] (user-id default: all users)
    get-package-display-name 
    get-package-path 
    get-package-uid  
    get-package-version-code 
    get-package-version-name 
    get-user-name [user-id] (user-id default: current user)
    install  [user-id] (user-id default: all users)
    install-sys  [device-install-dir]
    is-3rd-package  [user-id] (user-id default: all users)
    is-cmd-exists 
    is-file-exists 
    is-online
    is-only-one-user
    is-package-installed  [user-id] (user-id default: all users)
    is-pm-support-multiuser [apilevel]
    is-support-multiuser [apilevel]
    is-sys-package 
    is-user-exists 
    kill-package  [user-id] (user-id default: all users)
    list-3rd-packages [user-id] (user-id default: current user)
    list-packages [user-id] (user-id default: current user)
    list-sys-packages
    list-users
    make-pkg-installed-for-user  
    pull   [use-tmpdir]
    push   [use-tmpdir]
    remount-system-ro remount /system as read only
    remount-system-rw remount /system as read and write
    rootshell 
    shell 
    stop-package  [user-id] (user-id default: all users)
    uninstall  [user-id] (user-id default: all users)
    uninstall-sys 

Usage:
    deplaydroid update
    deplaydroid list fdroid
    deplaydroid list --cat --desc --ver --sug --pkg org.fdroid.fdroid
    deplaydroid install org.fdroid.fdroid=1007051
    deplaydroid backup --user cur org.fdroid.fdroid cf.vojtechh.apkmirror
    deplaydroid restore --user 10 --user 11 org.fdroid.fdroid
    deplaydroid restore --user 10 --user 11 ./data/default/user_0/org.fdroid.fdroid/appinfo.sh
    deplaydroid new-backup --3rd-app --3rd-data --freq-data --profile ./test.sh
    deplaydroid backup --profile ./test.sh
    deplaydroid restore --profile ./test.sh
    deplaydroid check-backup .

License

GNU General Public License, Version 3.0+