|
2 | 2 |
|
3 | 3 | An example Docker Compose project to run FlowFuse |
4 | 4 |
|
5 | | -## Prerequisites |
6 | | - |
7 | | -### Docker Compose |
8 | | - |
9 | | -FlowFuse uses Docker Compose to install and manager the required components. Instructions on how to install Docker Compose on your system can be found here: |
10 | | - |
11 | | -[https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/) |
12 | | - |
13 | | -FlowFuse requires at least Docker Compose v2 |
14 | | - |
15 | | -These instructions assume you are running Docker on a Linux or MacOS host system. |
16 | | - |
17 | | - |
18 | | -### DNS |
19 | | - |
20 | | -To access the Projects created you will need to set up a wildcard DNS entry that points to the `domain` entered in the `etc/flowforge.yml` file. |
21 | | - |
22 | | -e.g. assuming that Docker is running on a machine with IP address `192.168.0.8` then an A record point to `*.example.com`. |
23 | | - |
24 | | -This will mean that any host at `example.com` will resolve to the `192.168.0.8`. |
25 | | - |
26 | | -**Note** When testing locally you can not use the loopback address `127.0.0.1` for this, e.g. in the `/etc/hosts` file, as this will resolve to the TCP/IP stack inside each container. |
27 | | - |
28 | | -## Installing FlowFuse |
29 | | - |
30 | | -### Building Containers |
31 | | - |
32 | | -To build the required containers simply run `./build-containers.sh`. |
33 | | - |
34 | | -This will build and tag `flowfuse/forge-docker` and `flowfuse/node-red` and `flowfuse/file-server`. |
35 | | - |
36 | | -#### flowfuse/flowforge-docker |
37 | | - |
38 | | -This container holds the FlowFuse App and the Docker Driver. |
39 | | - |
40 | | -#### flowfuse/node-red |
41 | | - |
42 | | -This is a basic Node-RED image with the FlowFuse Launcher and the required Node-RED plugins to talk to the FlowFuse Platform. |
43 | | - |
44 | | -This is the container you can customize for your deployment. |
45 | | - |
46 | | -#### flowfuse/file-server |
47 | | - |
48 | | -This holds the Object Store used to allow persistent file storage for Projects running on Docker |
49 | | - |
50 | | -## Configuration |
51 | | - |
52 | | -Configuration details are stored in the `etc/flowforge.yml` file which is mapped into the `flowforge/forge-docker` container. You will need to edit this file to update the `domain` and `base_url` entries to match the DNS settings. |
53 | | - |
54 | | -You also need to update the `VIRTUAL_HOST` entry in the `docker-compose.yml` file to use the same domain as in the `etc/flowforge.yml` file. |
55 | | - |
56 | | -You should also update the `email` section to point to a local SMTP server so you can invite users to join teams. |
57 | | - |
58 | | -### Creating Instance |
59 | | - |
60 | | -Once the container have been built you can start the FlowFuse by running: |
61 | | - |
62 | | -``` |
63 | | -docker-compose -p flowforge up -d |
64 | | -``` |
65 | | - |
66 | | -This will also create a directory called `db` to hold the database files used to store project instance and user information. |
67 | | - |
68 | | -# Upgrading |
69 | | - |
70 | | -If upgrading from version before version 1.2.0 you will need to manually create the database for the persistent context store. |
71 | | - |
72 | | -To do this you will need to run the following command after starting: |
73 | | - |
74 | | -``` |
75 | | -docker exec -it flowforge_postgres_1 /docker-entrypoint-initdb.d/setup-context-db.sh |
76 | | -``` |
77 | | - |
78 | | -# Development Mode |
79 | | - |
80 | | -**This is experimental** |
81 | | - |
82 | | -If you are actively developing FlowFuse, the following instructions can be used |
83 | | -to run it with the Docker driver using a locally mounted source tree. |
84 | | - |
85 | | -1. Ensure that you have all of the FlowFuse source repositories checked out next to each |
86 | | -other - including this repository. |
87 | | - |
88 | | -2. Run `npm install` in each repository that has a package.json file. |
89 | | - |
90 | | -3. In the `flowforge` repo, run `npm run dev:local` to setup proper dev symlinks |
91 | | - between the repos. |
92 | | - |
93 | | -4. Follow the instructions above to setup DNS. |
94 | | - |
95 | | -5. Edit the `etc/flowforge.yml` file in the `flowforge` repository to use the docker driver: |
96 | | - ``` |
97 | | - port: 3000 |
98 | | - host: 0.0.0.0 |
99 | | - domain: example.com |
100 | | - base_url: http://forge.example.com |
101 | | - api_url: http://forge:3000 |
102 | | - |
103 | | - driver: |
104 | | - type: docker |
105 | | - options: |
106 | | - socket: /tmp/docker.sock |
107 | | - ``` |
108 | | - |
109 | | - |
110 | | -6. Depending on what OS you are running on, the core project has one binary |
111 | | - dependency that needs to be rebuilt for it to work inside Docker - `bcrypt`. |
112 | | - The super hacky way to get that to work is to edit `flowforge/package.json` and |
113 | | - modify the `serve` task to first reinstall that module: |
114 | | - ``` |
115 | | - "serve": "npm uninstall bcrypt && npm install bcrypt && npm-run-all --parallel build-watch start-watch" |
116 | | - ``` |
117 | | - You only need to do this the first time you run under docker - you can then revert |
118 | | - that change for the subsequent runs. |
119 | | - |
120 | | - **Note:** You will need to reinstall the module when you go back to running outside |
121 | | - of docker. |
122 | | - |
123 | | -7. Start the platform with: `docker-compose -f docker-compose-local-dev.yml up --build` |
124 | | - |
125 | | - That will start the standard environment, but the `forge` container will have the |
126 | | - local source tree mounted, and use `npm run serve` to start the code. This means |
127 | | - it will automatically rebuild/restart whenever source code changes are made. |
128 | | - |
129 | | - |
0 commit comments