|
| 1 | +# Advanced installation |
| 2 | +- Installation of TLS X.509 certificate (***Done in advanced usage***) |
| 3 | +- Agent configuration file and command line arguments |
| 4 | +- (Boot from PXE) and run HtP as a service (voucher, local disk,...) |
| 5 | +- Misc. |
| 6 | + |
| 7 | + |
| 8 | +## Installation in an airgapped/offline/oil-gapped system (**make a note about the binary**) |
| 9 | +If you are running Hashtopolis in an offline network or an air-gapped network, you will need to use a machine with internet access to either pull the images directly from the docker hub or build it yourself. |
| 10 | + |
| 11 | +Here are the commands to pull the images from Docker hub. To build the images from source, follow the instructions in the section related to building images. |
| 12 | +``` |
| 13 | +docker pull hashtopolis/backend:latest |
| 14 | +docker pull hashtopolis/frontend:latest |
| 15 | +``` |
| 16 | + |
| 17 | +The images can then be saved as .tar archives: |
| 18 | +``` |
| 19 | +docker save hashtopolis/backend:latest --output hashtopolis-backend.tar |
| 20 | +docker save hashtopolis/frontend:latest --output hashtopolis-frontend.tar |
| 21 | +``` |
| 22 | + |
| 23 | +Next, transfer both file to your Hashtopolis server and import them using the following commands |
| 24 | +``` |
| 25 | +docker load --input hashtopolis-backend.tar |
| 26 | +docker load --input hashtopolis-frontend.tar |
| 27 | +``` |
| 28 | + |
| 29 | +Continue with the normal docker installation described in ***link to the basic install*** |
| 30 | + |
| 31 | +## Build Hashtopolis images yourself |
| 32 | +The Docker images can be built from source following these steps. |
| 33 | + |
| 34 | +### Build frontend image |
| 35 | +1. Clone the Hashtopolis web-ui repository and cd into it. |
| 36 | +``` |
| 37 | +git clone https://github.com/hashtopolis/web-ui.git |
| 38 | +cd web-ui |
| 39 | +``` |
| 40 | + |
| 41 | +2. Build the web-ui repo and tag it |
| 42 | +``` |
| 43 | +docker build -t hashtopolis/frontend:latest --target hashtopolis-web-ui-prod . |
| 44 | +``` |
| 45 | + |
| 46 | +### Build backend image |
| 47 | +1. Move one directory back, clone the Hashtopolis server repository and cd into it: |
| 48 | +``` |
| 49 | +cd .. |
| 50 | +git clone https://github.com/hashtopolis/server.git |
| 51 | +cd server |
| 52 | +``` |
| 53 | + |
| 54 | +2. *(Optional)* Check the output of ```file docker-entrypoint.sh```. If it mentions *'with CRLF line terminators'*, your git checkout is converting line-ending on checkout. This is causing issues for files within the docker container. This is common behaviour for example within Windows (WSL) instances. To fix this: |
| 55 | +``` |
| 56 | +git config core.eol lf |
| 57 | +git config core.autocrlf input |
| 58 | +git rm -rf --cached . |
| 59 | +git reset --hard HEAD |
| 60 | +``` |
| 61 | + |
| 62 | +Check that ```file docker-entrypoint.sh``` correctly outputs: *'docker-entrypoint.sh: Bourne-Again shell script, ASCII text executable'*. |
| 63 | + |
| 64 | +3. Copy the env.example and edit the values to your likings |
| 65 | +``` |
| 66 | +cp env.example .env |
| 67 | +nano .env |
| 68 | +``` |
| 69 | + |
| 70 | +4. (Optional) If you want to test a preview of the version 2 of the UI, consult the New user interface technical preview section. (***Internal LINK***) |
| 71 | + |
| 72 | +5. Build the server docker image |
| 73 | +``` |
| 74 | +docker build . -t hashtopolis/backend:latest --target hashtopolis-server-prod |
| 75 | +``` |
| 76 | + |
| 77 | +## Using Local Folders outside of the Docker Volumes |
| 78 | + |
| 79 | +By default (when you use the default docker-compose) the Hashtopolis folder (import, files and binaries) are in a Docker volume. |
| 80 | + |
| 81 | +You can list this volume via docker volume ls. You can also access the volume directly in the backend, because it is mounted at: ```/usr/local/share/hashtopolis``` inside the container. |
| 82 | + |
| 83 | +However, if you do not want the use the volume but want to use folders of the host OS you can change the mount points in the docker compose file: |
| 84 | +``` |
| 85 | +version: '3.7' |
| 86 | +services: |
| 87 | + hashtopolis-backend: |
| 88 | + container_name: hashtopolis-backend |
| 89 | + image: hashtopolis/backend:latest |
| 90 | + restart: always |
| 91 | + volumes: |
| 92 | + # Where /opt/hashtopolis/<folder> are folders on you host OS. |
| 93 | + - /opt/hashtopolis/config:/usr/local/share/hashtopolis/config:Z |
| 94 | + - /opt/hashtopolis/log:/usr/local/share/hashtopolis/log:Z |
| 95 | + - /opt/hashtopolis/import:/usr/local/share/hashtopolis/import:Z |
| 96 | + - /opt/hashtopolis/binaries:/usr/local/share/hashtopolis/binaries:Z |
| 97 | + - /opt/hashtopolis/files:/usr/local/share/hashtopolis/files:Z |
| 98 | + environment: |
| 99 | + HASHTOPOLIS_DB_USER: $MYSQL_USER |
| 100 | + HASHTOPOLIS_DB_PASS: $MYSQL_PASSWORD |
| 101 | + HASHTOPOLIS_DB_HOST: $HASHTOPOLIS_DB_HOST |
| 102 | + HASHTOPOLIS_DB_DATABASE: $MYSQL_DATABASE |
| 103 | + HASHTOPOLIS_ADMIN_USER: $HASHTOPOLIS_ADMIN_USER |
| 104 | + HASHTOPOLIS_ADMIN_PASSWORD: $HASHTOPOLIS_ADMIN_PASSWORD |
| 105 | + HASHTOPOLIS_APIV2_ENABLE: $HASHTOPOLIS_APIV2_ENABLE |
| 106 | + depends_on: |
| 107 | + - db |
| 108 | + ports: |
| 109 | + - 8080:80 |
| 110 | + db: |
| 111 | + container_name: db |
| 112 | + image: mysql:8.0 |
| 113 | + restart: always |
| 114 | + volumes: |
| 115 | + - db:/var/lib/mysql |
| 116 | + environment: |
| 117 | + MYSQL_ROOT_PASSWORD: $MYSQL_ROOT_PASS |
| 118 | + MYSQL_DATABASE: $MYSQL_DATABASE |
| 119 | + MYSQL_USER: $MYSQL_USER |
| 120 | + MYSQL_PASSWORD: $MYSQL_PASSWORD |
| 121 | + hashtopolis-frontend: |
| 122 | + container_name: hashtopolis-frontend |
| 123 | + image: hashtopolis/frontend:latest |
| 124 | + environment: |
| 125 | + HASHTOPOLIS_BACKEND_URL: $HASHTOPOLIS_BACKEND_URL |
| 126 | + restart: always |
| 127 | + depends_on: |
| 128 | + - hashtopolis-backend |
| 129 | + ports: |
| 130 | + - 4200:80 |
| 131 | +volumes: |
| 132 | + db: |
| 133 | + hashtopolis: |
| 134 | +``` |
| 135 | + |
| 136 | +Make sure to copy everything out of the docker volume, you can do that using: |
| 137 | +``` |
| 138 | +docker cp hashtopolis-backend:/usr/local/share/hashtopolis <directory> |
| 139 | +``` |
| 140 | + |
| 141 | +Next, recreate the containers: |
| 142 | +``` |
| 143 | +docker compose down |
| 144 | +docker compose up |
| 145 | +``` |
| 146 | + |
| 147 | +Remember to copy the contents back into the folders. |
| 148 | + |
| 149 | +## Upgrading to 0.14.0 (from non-Docker to Docker) |
| 150 | +There are multiple ways to migrate the data from your non-docker setup to docker. You can of course completely start fresh; but if you want to migrate your data there are multiple ways to do this. |
| 151 | + |
| 152 | +### Existing database (**formerly called New database**) |
| 153 | +You can reuse your old database server or also migrate the database to a docker container. |
| 154 | + |
| 155 | +1. Install docker to your system (https://docs.docker.com/engine/install/ubuntu/) |
| 156 | +2. Create a database backup mysqldump <database-name> > hashtopolis-backup.sql |
| 157 | +3. Make copies of the following folders, can be found in the hashtopolis folder along side the index.php: |
| 158 | + - files |
| 159 | + - import |
| 160 | + - log |
| 161 | +4. Download the docker compose file: wget https://raw.githubusercontent.com/hashtopolis/server/master/docker-compose.yml |
| 162 | +5. Edit the docker compose file |
| 163 | +``` |
| 164 | +[...] |
| 165 | + hashtopolis-server: |
| 166 | +[...] |
| 167 | + volumes: |
| 168 | + - <path to where you want to store your hashtopolis files>:/usr/local/share/hashtopolis:Z |
| 169 | +[...] |
| 170 | +``` |
| 171 | + |
| 172 | +6. Download the env file |
| 173 | +``` |
| 174 | +wget https://raw.githubusercontent.com/hashtopolis/server/master/env.example -O .env |
| 175 | +``` |
| 176 | + |
| 177 | +7. Edit the .env file and change the settings to your likings nano .env |
| 178 | + - Optional: if you want to test the new API and new UI, set the HASHTOPOLIS_APIV2_ENABLE to 1 inside the .env file. NOTE: The APIv2 and UIv2 are a technical preview. Currently when enable everyone through the new API will be fully admin! |
| 179 | + - The HASHTOPOLIS_ADMIN_USER is only used during setup time and once you import the database backup will be replaced with your old data. |
| 180 | +8. Create the folder which to referred to in the docker-compose, in our example we will use /usr/local/share/hashtopolis |
| 181 | +``` |
| 182 | +sudo mkdir -p /usr/local/share/hashtopolis |
| 183 | +``` |
| 184 | + |
| 185 | +9. Copy the files, import, and log to the new location you refered to in the docker-compose file. |
| 186 | +``` |
| 187 | +sudo cp -r files/ import/ log/ /usr/local/share/hashtopolis |
| 188 | +``` |
| 189 | + |
| 190 | +10. In the same folder create a config folder: |
| 191 | +``` |
| 192 | +mkdir /usr/local/share/hashtopolis/config |
| 193 | +``` |
| 194 | + |
| 195 | +11. Start the docker container docker compose up |
| 196 | +12. Stop the backend container so that agents don't mess up the database mid migration docker |
| 197 | +``` |
| 198 | +stop hashtopolis-backend |
| 199 | +``` |
| 200 | + |
| 201 | +13. To migrate the data, first copy the database backup towards the db container: |
| 202 | +``` |
| 203 | +docker cp hashtopolis-backup.sql db:. |
| 204 | +``` |
| 205 | + |
| 206 | +14. Login on the container: |
| 207 | +``` |
| 208 | +docker exec -it db /bin/bash |
| 209 | +``` |
| 210 | + |
| 211 | +15. Import the data: |
| 212 | +``` |
| 213 | +mysql -Dhashtopolis -p < hashtopolis-backup.sql |
| 214 | +``` |
| 215 | + |
| 216 | +16. Exit the container |
| 217 | +17. Copy the content of the PEPPER from the *inc/conf.php* file and place them into *config/config*.json` |
| 218 | +Example */var/www/hashtopolis/inc/conf.php*: |
| 219 | +``` |
| 220 | +[...] |
| 221 | +$PEPPER = [..., ..., ..., ...]; |
| 222 | +[...] |
| 223 | +``` |
| 224 | +Becomes */usr/local/share/hashtopolis/config/config.json*: |
| 225 | +``` |
| 226 | +{ |
| 227 | + "PEPPER": [..., ..., ..., ...], |
| 228 | +} |
| 229 | +``` |
| 230 | + |
| 231 | +18. Restart the compose docker compose down && docker compose up |
| 232 | + |
| 233 | +### New database (**formerly called Existing database**) |
| 234 | + |
| 235 | +Repeat all the steps above, but you don't need to export/import the database. Only make sure that you point the settings inside the .env file to your database server and that the database server is reachable from your container. |
| 236 | + |
| 237 | +## Upgrading from docker to docker (version 0.14.0 and up) |
| 238 | +1. Stop your docker compose docker compose down |
| 239 | +2. docker compose pull |
| 240 | +3. docker compose up |
| 241 | + |
| 242 | +## Upgrading from docker to docker (version 0.14.0 and up) - Offline System(s) |
| 243 | + |
| 244 | +***To be done*** |
| 245 | + |
| 246 | +## New user interface technical preview (**also present in basic install**) |
| 247 | +> [!NOTE]: |
| 248 | +> The APIv2 and UIv2 are a technical preview. Currently, when enabled, everyone through the new API will be fully admin! |
| 249 | +
|
| 250 | +To enable 'version 2' of the API: |
| 251 | + |
| 252 | +1. Stop your containers |
| 253 | +2. set the *HASHTOPOLIS_APIV2_ENABLE* to 1 inside the *.env* file. |
| 254 | +3. ```docker compose up --detach``` |
| 255 | +4. Access the technical preview via: http://127.0.0.1:4200 using the credentials below (unless modified in the *.env* file) |
| 256 | + - user: admin |
| 257 | + - password: hashtopolis |
0 commit comments