DOCSEARCHbyAlgolia
Submit Docs

DockSTARTer Documentation

repository·main·Indexed 25 days ago

https://github.com/ghostwriters/dockstarter

A tool for quick setup and management of Docker containers featuring an interactive CLI menu for application selection and configuration. It supports multiple Linux distributions (Alpine, Debian, Ubuntu, Fedora, Arch, CentOS) and MacOS, providing a structured system for managing global settings via .env files, automated installation scripts, and a comprehensive logging and initialization lifecycle.

Tokens
2.8K
Snippets
6
Records
14
Agent score
83%

What's inside DockSTARTer

  2. Install DockSTARTer on MacOS

    main

    To install DockSTARTer on MacOS, use Homebrew to install dependencies and Docker, then run the installation script.

    Step 1: Install Dependencies

    brew install bash curl git grep gnu-sed

    Step 2: Run Installer

    bash -c "$(curl -fsSL https://get.dockstarter.com)"
sudo reboot

    Required Post-Installation Steps:

    1. Enable Docker at Startup: In Docker Desktop settings, ensure "Start Docker Desktop when you sign in to your computer" is enabled in the General heading.
    2. Approve Keychain Permissions: Open terminal.app from the MacOS desktop and run the command ds -c. When the keychain access dialog appears, enter your MacOS login password and click "Always Allow".
    brew install bash curl git grep gnu-sed
bash -c "$(curl -fsSL https://get.dockstarter.com)"
sudo reboot

  3. Run and Configure DockSTARTer

    main

    Once installed, you can launch the DockSTARTer interactive menu using the ds command.

    To perform an initial setup:

    1. Run ds in your terminal.
    2. Navigate to Configuration in the main menu.
    3. Select Full Setup to be guided through selecting applications and starting containers.
    ds

  4. Install DockSTARTer via Git (Alternate Method)

    main

    If you prefer not to use the direct curl-to-bash installation method, you can clone the repository manually. First, install the required dependencies for your distribution:

    • APT: sudo apt-get install curl git
    • DNF: sudo dnf install curl git
    • Pacman: sudo pacman -Sy curl git
    • YUM: sudo yum install curl git
    • MacOS: brew install bash curl git grep gnu-sed

    Then, clone the repository and run the main script:

    git clone https://github.com/GhostWriters/DockSTARTer "/home/${USER}/.dockstarter"
bash /home/"${USER}"/.dockstarter/main.sh -vi
sudo reboot
    git clone https://github.com/GhostWriters/DockSTARTer "/home/${USER}/.dockstarter"
bash /home/"${USER}"/.dockstarter/main.sh -vi
sudo reboot

  5. Install DockSTARTer on Linux

    main

    Install DockSTARTer by running the appropriate command for your Linux distribution. After running the installation commands, a system reboot is required.

    Alpine (APK)

    sudo apk add curl git
bash -c "$(curl -fsSL https://get.dockstarter.com)"
sudo reboot

    Debian/Ubuntu (APT)

    sudo apt-get install curl git
bash -c "$(curl -fsSL https://get.dockstarter.com)"
sudo reboot

    Note for Raspbian: Raspbian requires an update and Docker installation first:

    sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get install curl git
bash -c "$(curl -fsSL https://get.docker.com)"
bash -c "$(curl -fsSL https://get.dockstarter.com)"
sudo reboot

    Fedora (DNF)

    sudo dnf install curl git
bash -c "$(curl -fsSL https://get.dockstarter.com)"
sudo reboot

    Arch/Manjaro/EndeavourOS (Pacman)

    sudo pacman -Sy curl docker git
bash -c "$(curl -fsSL https://get.dockstarter.com)"
sudo reboot

    CentOS (YUM)

    sudo yum install curl git
bash -c "$(curl -fsSL https://get.dockstarter.com)"
sudo reboot
    bash -c "$(curl -fsSL https://get.dockstarter.com)"

  6. Understand the DockSTARTer initialization lifecycle

    main

    When you run the DockSTARTer script, it executes an init sequence to ensure the environment is correctly configured before performing any actions. The init function performs the following checks in order:

    1. System Compatibility: init_check_system verifies the environment meets requirements.
    2. Repository Integrity: init_check_cloned and init_check_templates ensure both the main repository and the templates repository are properly cloned.
    3. Terminal Access: init_check_tty verifies the terminal is writable.
    4. Dependencies: init_check_dependencies ensures all required software is installed.
    5. Git State: init_check_branch verifies you are on the expected branch.
    6. Symlinks: init_check_symlink ensures necessary symlinks are present.
    7. Updates: init_check_update checks for available updates for both the application and templates.

    If any of these checks fail, the script will typically error out or warn the user before proceeding to the main logic.

  7. Execute DockSTARTer main logic

    main

    The primary execution flow of the script follows this pattern:

    1. Initialization: Runs the init sequence to validate the environment.
    2. Configuration Application: Runs run_script 'apply_config' to ensure system configurations are applied.
    3. Command Execution: Passes any provided CLI arguments to the cmdline function to execute the requested user command.

  8. Understand DockSTARTer system requirements

    main

    DockSTARTer has specific environment and system requirements to function correctly:

    • Bash Version: Requires at least bash version 4.
    • Architecture: Supports aarch64 (including arm64) or x86_64.
    • User Permissions:
      • Do not run as root: Running as the root user is not supported.
      • Do not run with sudo: Commands requiring sudo will prompt automatically when needed. Running the script itself with sudo is not supported.
    • Terminal: Requires a writable TTY for interactive use.

  9. Run DockSTARTer via the bootstrap command

    main

    If you do not have the DockSTARTer repository cloned locally, you can run the bootstrap command to clone the repository into your home directory (defaulting to ~/.dockstarter) and perform an initial installation.

    When run without arguments, it performs a first-run install with the following flags: -yvi --config-show.

    clone_repo

  10. Update DockSTARTer using the -u flag

    main
    DockSTARTer includes an automatic update check mechanism. If an update is available for the main application or the templates, the script will notify you via a warning message. To perform an update, use the -u flag with the main application command. You can also specify a specific branch to update to (e.g., a stable release branch).

  11. Configure Global Settings in .env

    main

    DockSTARTer uses a .env file to manage global configuration. Key settings include directory paths for Docker configurations and volumes, network settings, user/group IDs, and storage mounting toggles.

    Important Path Variables:

    • HOME: The base home directory.
    • DOCKER_CONFIG_FOLDER: The directory where Docker configuration files are stored.
    • DOCKER_COMPOSE_FOLDER: The directory where Docker Compose files are stored.
    • DOCKER_VOLUME_CONFIG: Defaults to ${DOCKER_CONFIG_FOLDER}/appdata.
    • DOCKER_VOLUME_STORAGE: The primary storage location (defaults to ${HOME}/storage).

    User and System IDs:

    • PUID and PGID: The User ID and Group ID used for container permissions.
    • DOCKER_GID: The Docker group ID.
    • TZ: The timezone for the system.

    Storage Management:

    • DOCKER_MULTIPLE_STORAGE: Set to ON to enable support for multiple storage locations.
    • DOCKER_STORAGE_ON: Controls mounting of the first storage location (YES or NO).
    • DOCKER_STORAGE2_ON through DOCKER_STORAGE4_ON: Controls mounting of additional storage locations.
    HOME=''
DOCKER_CONFIG_FOLDER=''
DOCKER_COMPOSE_FOLDER=''

DOCKER_VOLUME_CONFIG="${DOCKER_CONFIG_FOLDER?}/appdata"
DOCKER_VOLUME_STORAGE="${HOME?}/storage"
DOCKER_VOLUME_STORAGE2="${HOME?}/storage2"
DOCKER_VOLUME_STORAGE3="${HOME?}/storage3"
DOCKER_VOLUME_STORAGE4="${HOME?}/storage4"
DOCKER_VOLUME_DOCKER_SOCKET='/var/run/docker.sock'

DOCKER_HOSTNAME=''
GLOBAL_LAN_NETWORK='192.168.x.x/24'
GLOBAL_NS1='1.1.1.1'
GLOBAL_NS2='8.8.8.8'

DOCKER_GID='x999x'
PGID='x1000x'
PUID='x1000x'
TZ=''

COMPOSE_HTTP_TIMEOUT='60'

DOCKER_MULTIPLE_STORAGE='OFF' # Set to ON to enable multiple storage location support
DOCKER_STORAGE_ON='YES'       # Set to NO to disable mounting storage location 1
DOCKER_STORAGE2_ON='NO'       # Set to YES to enable mounting storage location 2
DOCKER_STORAGE3_ON='NO'       # Set to YES to enable mounting storage location 3
DOCKER_STORAGE4_ON='NO'       # Set to YES to enable mounting storage location 4

  12. Use the logging system (trace, debug, info, notice, warn, error, fatal)

    main

    DockSTARTer provides a structured logging system that handles both terminal output (with colors) and file logging.

    Log Levels:

    • trace(): Detailed diagnostic information.
    • debug(): Debugging information.
    • info(): General informational messages.
    • notice(): Important non-error notifications.
    • warn(): Warning messages.
    • error(): Error messages.
    • fatal(): Critical errors that stop execution. fatal() automatically generates a full system information and stack trace, writes it to a fatal log, and exits the script.

    Log Files:

    • Standard Log: Located at ${XDG_CONFIG_HOME}/dockstarter/dockstarter.log.
    • Fatal Log: Located at ${XDG_CONFIG_HOME}/dockstarter/dockstarter.fatal.log (only used by fatal()).