Skip to content
This repository has been archived by the owner on Apr 14, 2023. It is now read-only.

Commit

Permalink
updated documentation for bootloader
Browse files Browse the repository at this point in the history
  • Loading branch information
@adpham95
adpham95 committed Jul 22, 2019
1 parent fd5456c commit 1fa8dd3
Show file tree
Hide file tree
Showing 3 changed files with 193 additions and 67 deletions.
98 changes: 76 additions & 22 deletions README.md
View file
Expand Up @@ -17,45 +17,99 @@ Documentation
------------------------
https://walkoff.readthedocs.io/en/latest/

Deploying WALKOFF
Pre-requisites
------------------------
**Ensure that Docker, Docker-Compose 3+, and git are installed**
**Ensure that Docker, Docker Compose 3+, and git are installed!**

1. Open a terminal on Linux or a command prompt on Windows, and clone the Walkoff project.
* Docker CE: https://docs.docker.com/install/#supported-platforms
* Docker Compose: https://docs.docker.com/compose/install/
* Git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

If you do not already have a Docker Swarm initialized or joined, run the following command to create one:

docker swarm init

**Note:** If you have multiple NICs you will need to use --advertise-addr to pick an address from which the swarm will be accessible.

Deploying WALKOFF in a Unix environment
---------------------------------------

1. Open a terminal and clone WALKOFF:

git clone https://github.com/nsacyber/WALKOFF.git

2. Change directories to the WALKOFF directory
2. Move into the WALKOFF directory:

cd WALKOFF

3. Perform the following command to launch WALKOFF in swarm mode
3. Build WALKOFF's bootloader container, which handles management of the WALKOFF stack:

./build_bootloader.sh
The bootloader performs the following tasks:
* Creating Docker secrets, configs, networks, volumes, etc.
* Building and pushing component images to WALKOFF's internal registry.
* Deploying and removing the Docker Stack.

4. Launch WALKOFF with the bootloader, building components as well:

./walkoff.sh up --build

# If verbose output is desired:
./walkoff.sh up --build --debug

5. Navigate to the default IP and port. The default IP and the port can be changed by altering the port NGINX is exposed on (the right-hand port) in the top-level `docker-compose.yml`. Note that you should use HTTPS, and allow the self-signed certificate when prompted.

https://127.0.0.1:8080

6. The default username is "admin" and password is "admin." These can and should be changed upon initial login.

7. To stop WALKOFF, use the bootloader:

./walkoff.sh down

# If removing encryption key (and persistent data), stored images, and verbose output is desired:
./walkoff.sh down --key --registry --debug


Deploying WALKOFF in a Windows environment
------------------------------------------

1. Open PowerShell and clone WALKOFF:

git clone https://github.com/nsacyber/WALKOFF.git

2. Move into the WALKOFF directory:

cd WALKOFF

3. Use the provided `walkoff.ps1` script to initialize Walkoff's required components:

# Create Docker volumes, secrets
.\walkoff.ps1 init

docker swarm init
# Build and Push WALKOFF component images
.\walkoff.ps1 build

**Note:** If you have multiple NICs you will need to use --advertise-addr to pick an address from which the swarm will be accessible.
4. Launch WALKOFF with `walkoff.ps1`:

4. Create an encryption key
# Deploy WALKOFF stack
.\walkoff.ps1 up

docker run python:3.7-alpine python -c "import os, base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())" | docker secret create walkoff_encryption_key -
# Check WALKOFF stack services
.\walkoff.ps1 status

5. Create data/registry directory

mkdir data/registry
5. Navigate to the default IP and port. The default IP and the port can be changed by altering the port NGINX is exposed on (the right-hand port) in the top-level `docker-compose.yml`. Note that you should use HTTPS, and allow the self-signed certificate when prompted.

6. Perform the following command to launch WALKOFF with stack mode
https://127.0.0.1:8080

docker-compose build
docker stack deploy --compose-file docker-compose.yml walkoff
6. The default username is "admin" and password is "admin." These can and should be changed upon initial login.

7. Navigate to the default IP and port. The default IP and the port can be changed in the server. Configuration settings will be saved in the ``common/config.py`` file. Walkoff now uses HTTPS by default through NGINX.
7. To stop WALKOFF, use the bootloader:

https://localhost:8080
.\walkoff.ps1 stop

8. Once navigated to the login page, the default username is "admin" and password is "admin." These can and should be changed upon initial login.
# If removing encryption key, persistent data, stored images is desired:
.\walkoff.ps1 down

9. To shutdown WALKOFF, run the following two commands. The first command may not remove all services; as the Umpire container exits, it will try to clean up the rest. Run the command again after a few seconds; if it does not fully clean up, you will have to manually remove services.

docker stack rm walkoff
# Some seconds later
docker stack rm walkoff
53 changes: 27 additions & 26 deletions docs/apps.rst
View file
Expand Up @@ -107,36 +107,35 @@ If you would like to follow along by adding a VirusTotal app to your Walkoff ins
**6. Change the** ``requirements.txt`` **to match your applications needs**
* This file should include any Python package dependencies your app contains
* The Dockerfile will use this to pip install dependencies
* **EXAMPLE:**
.. code-block:: python
* **EXAMPLE:**

.. code-block:: python
requests
requests
**7. Change the** ``docker-compose`` **YAML file**
* This will control how your app’s Docker container will run.
* At a minimum, utilize the ``hello_world`` application's ``docker-compose.yml`` and simply change the service name to match that of your new application.
**7. Edit** ``docker-stack-windows.yml`` **(Windows only)**
* At the current time, the WALKOFF "Bootloader" for Windows is rather basic due to time constraints. It will be brought up to the same functionality as the Linux version once time allows.
* Copy an existing app service definition and change the service name to match your app's directory name.
* **Note:** If you want directories on your host to be available in the container, you can add volume mounts here.
* **EXAMPLE:**

.. code-block:: html

version: '3.4'
services:
virus_total:
build:
context: .
dockerfile: Dockerfile
# image: walkoff_registry:5000/walkoff_app_HelloWorld-v1-0
env_file:
- env.txt
deploy:
mode: replicated
replicas: 10
restart_policy:
condition: none
placement:
constraints: [node.role==manager]
restart: "no"

.. code-block:: yaml
services:
<other service definitions>
app_virus_total:
build:
context: apps/walk_off/1.0.0
dockerfile: Dockerfile
configs:
- common_env.yml
deploy:
mode: replicated
replicas: 0
restart_policy:
condition: none
image: 127.0.0.1:5000/walkoff_app_virus_total:1.0.0
**Optional:** ``Dockerfile`` **Customization**
* This will control how your app will be built.
Expand All @@ -153,6 +152,8 @@ Updating Your Application
''''''''''''''''''''''''''''
If your application Docker service is already running and you would like to update your app in WALKOFF, run these following commands with the proper substitions for application name ``hello_world``

Watch this space for updates - we're currently working on an app editor UI component that should make this much easier.

.. code-block:: console
app_dir=apps/hello_world/1.0.0
Expand Down
109 changes: 90 additions & 19 deletions docs/index.rst
View file
Expand Up @@ -20,58 +20,129 @@ WALKOFF is a flexible, easy to use, automation framework allowing users to integ

.. _deploying-walkoff-label:

Deploying WALKOFF
Pre-requisites
------------------------
**Ensure that Docker, Docker-Compose 3+, and git are installed**
**Ensure that Docker, Docker Compose 3+, and git are installed!**

#. Open a terminal on Linux or a command prompt on Windows, and clone WALKOFF:
* Docker CE: https://docs.docker.com/install/#supported-platforms
* Docker Compose: https://docs.docker.com/compose/install/
* Git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

If you do not already have a Docker Swarm initialized or joined, run the following command to create one:

.. code-block:: console
git clone https://github.com/nsacyber/WALKOFF.git
docker swarm init
#. Change directories to the WALKOFF directory:
**Note:** If you have multiple NICs you will need to use --advertise-addr to pick an address from which the swarm will be accessible.

.. code-block:: console
Deploying WALKOFF in a Unix environment
---------------------------------------

cd WALKOFF
#. Open a terminal and clone WALKOFF:

.. code-block:: console
#. Perform the following command to create a Docker Swarm with your host as the manager:
git clone https://github.com/nsacyber/WALKOFF.git
.. code-block:: console
#. Move into the WALKOFF directory:

.. code-block:: console
docker swarm init
cd WALKOFF
**Note:** If you have multiple NICs you will need to use --advertise-addr to pick an address from which the swarm will be accessible.
#. Build WALKOFF's bootloader container, which handles management of the WALKOFF stack:

#. Build WALKOFF's bootloader:
* Creating Docker secrets, configs, networks, volumes, etc.
* Building and pushing component images to WALKOFF's internal registry.
* Deploying and removing the Docker Stack.

.. code-block:: console
./build_bootloader.sh
./build_bootloader.sh
#. Launch WALKOFF with the bootloader, building components as well:

.. code-block:: console
./walkoff.sh up --build
./walkoff.sh up --build
# If verbose output is desired:
./walkoff.sh up --build --debug
#. Navigate to the default IP and port. The default IP and the port can be changed by altering the port NGINX is exposed on (the right-hand port) in the top-level `docker-compose.yml`. Note that you should use HTTPS, and allow the self-signed certificate when prompted.

.. code-block:: console
https://127.0.0.1:8080
#. Navigate to the default IP and port. The default IP and the port can be changed by altering the port NGINX is exposed on (the right-hand port) in the top-level `docker-compose.yml`.
#. The default username is "admin" and password is "admin." These can and should be changed upon initial login.


#. To stop WALKOFF, use the bootloader:

.. code-block:: console
./walkoff.sh down
# If removing encryption key (and persistent data), stored images, and verbose output is desired:
./walkoff.sh down --key --registry --debug
Deploying WALKOFF in a Windows environment
------------------------------------------

#. Open PowerShell and clone WALKOFF:

.. code-block:: console
https://127.0.0.1:8080
git clone https://github.com/nsacyber/WALKOFF.git
#. Once navigated to the login page, the default username is "admin" and password is "admin." These can and should be changed upon initial login.
#. Move into the WALKOFF directory:

.. code-block:: console
cd WALKOFF
#. To shutdown WALKOFF, use the bootloader:
#. Use the provided `walkoff.ps1` script to initialize Walkoff's required components:

.. code-block:: console
./walkoff.sh down
# Create Docker volumes, secrets
.\walkoff.ps1 init
# Build and Push WALKOFF component images
.\walkoff.ps1 build
#. Launch WALKOFF with `walkoff.ps1`:

.. code-block:: console
# Deploy WALKOFF stack
.\walkoff.ps1 up
# Check WALKOFF stack services
.\walkoff.ps1 status
#. Navigate to the default IP and port. The default IP and the port can be changed by altering the port NGINX is exposed on (the right-hand port) in the top-level `docker-compose.yml`. Note that you should use HTTPS, and allow the self-signed certificate when prompted.

.. code-block:: console
https://127.0.0.1:8080
#. The default username is "admin" and password is "admin." These can and should be changed upon initial login.


#. To stop WALKOFF, use the bootloader:

.. code-block:: console
.\walkoff.ps1 stop
# If removing encryption key, persistent data, stored images is desired:
.\walkoff.ps1 down
Expand Down

0 comments on commit 1fa8dd3

Please sign in to comment.