Skip to content

Commit 4ecb55f

Browse files
aarranzaarranz
committed
Update README.md with latest changes
1 parent 54a32a1 commit 4ecb55f

2 files changed

Lines changed: 205 additions & 63 deletions

File tree

‎README.md‎

Lines changed: 205 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,229 @@
11
# Supported tags and respective `Dockerfile` links #
22

3-
- [`1.1`, `latest`](https://github.com/Wirecloud/docker-wirecloud/blob/master/1.1/Dockerfile)
3+
- [`1.2`, `latest`](https://github.com/Wirecloud/docker-wirecloud/blob/master/1.2/Dockerfile)
4+
- [`1.1`](https://github.com/Wirecloud/docker-wirecloud/blob/master/1.1/Dockerfile)
45
- [`1.1-composable`, `latest-composable`](https://github.com/Wirecloud/docker-wirecloud/blob/master/1.1-composable/Dockerfile)
56
- [`1.0`](https://github.com/Wirecloud/docker-wirecloud/blob/master/1.0/Dockerfile)
67
- [`1.0-composable`](https://github.com/Wirecloud/docker-wirecloud/blob/master/1.0-composable/Dockerfile)
7-
- [`0.9`](https://github.com/Wirecloud/docker-wirecloud/blob/master/0.9/Dockerfile)
8-
- [`0.9-composable`](https://github.com/Wirecloud/docker-wirecloud/blob/master/0.9-composable/Dockerfile)
98
- [`dev`](https://github.com/Wirecloud/docker-wirecloud/blob/master/dev/Dockerfile)
10-
- [`dev-composable`](https://github.com/Wirecloud/docker-wirecloud/blob/master/dev-composable/Dockerfile)
119

1210

13-
## What is WireCloud?
11+
# What is WireCloud?
1412

1513
WireCloud builds on cutting-edge end-user development, RIA and semantic technologies to offer a next-generation end-user centred web application mashup platform aimed at leveraging the long tail of the Internet of Services. WireCloud builds on cutting-edge end-user (software) development, RIA and semantic technologies to offer a next-generation end-user centred web application mashup platform aimed at allowing end users without programming skills to easily create web applications and dashboards/cockpits (e.g. to visualize their data of interest or to control their domotized home or environment). Web application mashups integrate heterogeneous data, application logic, and UI components (widgets) sourced from the Web to create new coherent and value-adding composite applications. They are targeted at leveraging the "long tail" of the Web of Services (a.k.a. the Programmable Web) by exploiting rapid development, DIY, and shareability. They typically serve a specific situational (i.e. immediate, short-lived, customized) need, frequently with high potential for reuse. Is this "situational" character which precludes them to be offered as 'off-the-shelf' functionality by solution providers, and therefore creates the need for a tool like WireCloud
1614

1715
WireCloud is part of [FIWARE](https://www.fiware.org/). Check it out in the [Catalogue](https://catalogue.fiware.org/enablers/application-mashup-wirecloud)
1816

1917
[![WireCloud's logo](https://raw.githubusercontent.com/Wirecloud/docker-wirecloud/master/logo.png)](https://github.com/Wirecloud/wirecloud)
2018

21-
## How to use these images.
2219

23-
There are two types of images, the "standalone" images and the "composable" images. The standalone images comes with everything ready to run WireCloud directly by running the image and without having to configure it (no recommended for production). The composable images are designed to work with `docker-compose` and support a more flexible configuration scheme.
20+
# How to use this image
2421

25-
## Standalone
22+
```
23+
$ docker run --name some-wirecloud -p 80:8000 -e DEBUG=True -d fiware/wirecloud
24+
```
2625

27-
Running the standalone images are really simple:
26+
The following environment variables are also honored for configuring your WireCloud instance:
27+
28+
- `-e DEBUG=...` (defaults to "False", use "True" for running WireCloud in debug
29+
mode. Debug mode should be enabled for running WireCloud in standalone mode)
30+
- `-e DEFAULT_THEME=...` (defaults to "wirecloud.defaulttheme")
31+
- `-e DB_HOST=...` (defaults to nothing, provide a host value to connect this
32+
image with a DB server)
33+
- `-e DB_NAME=...` (defaults to "postgres")
34+
- `-e DB_USERNAME=...` (defaults to "postgres")
35+
- `-e DB_PASSWORD=...` (defaults to "postgres")
36+
- `-e FORWARDED_ALLOW_IPS=...` (defaults to "*", set this to provide a list of
37+
trusted reverse proxies)
38+
- `-e ELASTICSEARCH2_URL=...` (defaults to nothing, leave it empty to use Whoosh
39+
instead).
40+
- `-e MEMCACHED_LOCATION=...` (defaults to nothing, leave it empty to disable
41+
memcached support)
42+
- `-e FIWARE_IDM_SERVER=...` (defaults to nothing, leave it empty for
43+
authenticating users using the credentials stored on the WireCloud
44+
database.)
45+
- `-e SOCIAL_AUTH_FIWARE_KEY=...` (defaults to nothing)
46+
- `-e SOCIAL_AUTH_FIWARE_SECRET=...` (defaults to nothing)
47+
48+
When running WireCloud with TLS behind a reverse proxy such as Apache/NGINX
49+
which is responsible for doing TLS termination, be sure to set
50+
the `X-Forwarded-Proto`, `X-Forwarded-Host` and `X-Forwarded-Port` headers
51+
appropriately.
52+
53+
54+
## Running manage.py commands
55+
56+
You can run any available `manage.py` command by using `docker exec -ti some-wirecloud manage.py ...`. For example, you can create superusers/administrators by running the following command:
57+
58+
```
59+
$ docker exec -ti some-wirecloud manage.py createsuperuser
60+
Username (leave blank to use 'root'): admin
61+
Email address: ${youremail}
62+
Password: ${yourpassword}
63+
Password (again): ${yourpassword}
64+
Superuser created successfully.
65+
```
66+
67+
Regarding commands using the filesystem, take into account that those commands will be executed inside the container and thus the filesystem will be the one used by the container. The `manage.py` script will not check if those commands make changes outside the provided volumes. Anyway, they can be used without any problem. For example, static files can be collected using the following command:
2868

2969
```
30-
$ docker run --name some-wirecloud -d -p 80:80 fiware/wirecloud:latest
70+
$ docker exec -ti some-wirecloud manage.py collectstatic
3171
```
3272

33-
This example uses the `latest` version, but it should work also with versions `1.1`, `1.0` and `0.9`. Those images includes `EXPOSE 80` (the http port) so them can be used directly to serve WireCloud. Remember that those images are not meant to be used on production that will require configuring HTTPS.
73+
Use `docker exec -ti some-wirecloud manage.py --help` for getting the list of available commands.
3474

35-
### Customizations
3675

37-
The standalone image uses a volume for `/opt/wirecloud_instance` (the path where the WireCloud instance is stored), this means that any change you make to the `settings.py` file will be persisted.
76+
## ... via `docker stack deploy` or `docker-compose`
3877

39-
If you want to use a different theme, you can create it on `/opt/wirecloud_instance`. See the [documentation](https://wirecloud.readthedocs.io/en/stable/development/platform/themes/) for more info.
78+
Example `docker-compose.yml` for WireCloud:
4079

41-
> **Note**: Rembember that any change made outside the defined volume will be lost if the image is updated.
80+
```yaml
81+
version: "3"
4282

43-
## Composable
83+
services:
84+
85+
nginx:
86+
restart: always
87+
image: nginx
88+
ports:
89+
- 80:80
90+
volumes:
91+
- ./nginx.conf:/etc/nginx/nginx.conf:ro
92+
- ./wirecloud-static:/var/www/static:ro
93+
depends_on:
94+
- wirecloud
95+
96+
97+
postgres:
98+
restart: always
99+
image: postgres
100+
environment:
101+
- POSTGRES_PASSWORD=wirepass # Change this password!
102+
volumes:
103+
- ./postgres-data:/var/lib/postgresql/data
104+
105+
106+
elasticsearch:
107+
restart: always
108+
image: elasticsearch:2.4
109+
volumes:
110+
- ./elasticsearch-data:/usr/share/elasticsearch/data
111+
command: elasticsearch -Des.index.max_result_window=50000
44112

45-
This image is meant to be used with `docker-compose`.
46113

47-
[Docker compose](https://docs.docker.com/compose/) is a tool that allows you to defining and running multi-container applications with Docker.
114+
memcached:
115+
restart: always
116+
image: memcached:1
117+
command: memcached -m 2048m
118+
119+
120+
wirecloud:
121+
restart: always
122+
image: fiware/wirecloud
123+
depends_on:
124+
- postgres
125+
- elasticsearch
126+
- memcached
127+
environment:
128+
- DEBUG=False
129+
# - DEFAULT_THEME=wirecloud.defaulttheme
130+
- DB_HOST=postgres
131+
- DB_PASSWORD=wirepass # Change this password!
132+
- FORWARDED_ALLOW_IPS=*
133+
- ELASTICSEARCH2_URL=http://elasticsearch:9200/
134+
- MEMCACHED_LOCATION=memcached:11211
135+
# Uncomment the following environment variables to enable IDM integration
136+
#- FIWARE_IDM_SERVER=${FIWARE_IDM_SERVER}
137+
#- SOCIAL_AUTH_FIWARE_KEY=${SOCIAL_AUTH_FIWARE_KEY}
138+
#- SOCIAL_AUTH_FIWARE_SECRET=${SOCIAL_AUTH_FIWARE_SECRET}
139+
volumes:
140+
- ./wirecloud-data:/opt/wirecloud_instance/data
141+
- ./wirecloud-static:/var/www/static
142+
```
143+
144+
This `docker-compose.yml` file relies on a `nginx.conf` configuration file:
145+
146+
```nginx
147+
user nginx;
148+
worker_processes 1;
149+
150+
error_log /var/log/nginx/error.log warn;
151+
pid /var/run/nginx.pid;
152+
48153
49-
First, install docker compose following [this steps](https://docs.docker.com/compose/install/)
154+
events {
155+
worker_connections 1024;
156+
}
157+
158+
159+
http {
160+
include /etc/nginx/mime.types;
161+
default_type application/octet-stream;
162+
163+
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
164+
'$status $body_bytes_sent "$http_referer" '
165+
'"$http_user_agent" "$http_x_forwarded_for"';
50166
51-
> Take into account that some users have reporeted errors when instaing docker-compose from pip.
167+
access_log /var/log/nginx/access.log main;
52168
53-
You can use [this example `docker-compose.yml` file](https://github.com/Wirecloud/docker-wirecloud/blob/master/hub-docs/docker-compose.yml):
169+
sendfile on;
170+
#tcp_nopush on;
171+
172+
keepalive_timeout 65;
173+
174+
#gzip on;
175+
176+
server {
177+
178+
listen 80;
179+
server_name example.org;
180+
client_max_body_size 20M;
181+
charset utf-8;
182+
183+
location /static {
184+
alias /var/www/static;
185+
}
186+
187+
location / {
188+
proxy_pass http://wirecloud:8000;
189+
proxy_set_header Host $host;
190+
proxy_set_header X-Real-IP $remote_addr;
191+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
192+
}
193+
194+
}
195+
}
196+
```
197+
198+
Run `docker stack deploy -c docker-compose.yml wirecloud` (or `docker-compose -f docker-compose.yml up`), wait for it to initialize completely, and visit `http://swarm-ip`, `http://localhost`, or `http://host-ip` (as appropriate). Also, take into account that you should configure https to have a production-ready deployment of WireCloud (not covered by this example).
199+
200+
201+
## Customizations
202+
203+
If you want to customize your WireCloud installation, the best option is to create a new docker image by extending one of the official images and installing new modules. For example, you can follow the following [tutorial](https://wirecloud.readthedocs.io/en/stable/development/platform/themes/) for creating a custom theme and install it on the extended image and use the `DEFAULT_THEME` environment variable to configure it as the default theme.
204+
205+
206+
# Using previous versions (WireCloud v1.1 and below)
207+
208+
WireCloud v1.1 and below uses two images, the "standalone" images and the "composable" images. The standalone images comes with everything ready to run WireCloud directly by running the image and without having to configure it (no recommended for production). The composable images are designed to work with other services running on other containers (e.g. using `docker-compose` or docker swarm) supporting a more flexible configuration scheme.
209+
210+
211+
## Standalone
212+
213+
Running the standalone images are really simple:
214+
215+
```
216+
$ docker run --name some-wirecloud -d -p 80:80 fiware/wirecloud:1.1
217+
```
218+
219+
This example uses the `1.1` version, but it should work also with versions `1.0`. Those images includes `EXPOSE 80` (the http port) so them can be used directly to serve WireCloud. In any case, those images are not meant to be used on production that will require, at least, configuring HTTPS.
220+
221+
222+
## Composable
223+
224+
This image is meant to be used running some services (e.g. database) outside the main WireCloud container, that is, deployed manually or deployed using other docker images.
225+
226+
You can make use of [Docker compose](https://docs.docker.com/compose/) as well as [this example `docker-compose.yml` file](https://github.com/Wirecloud/docker-wirecloud/blob/master/hub-docs/docker-compose.yml) for deploying all the required services:
54227

55228
```yaml
56229
version: "3.1"
@@ -85,7 +258,7 @@ services:
85258
- ./static:/var/www/static
86259
```
87260

88-
and [this `nginx.conf` file](https://github.com/Wirecloud/docker-wirecloud/blob/master/hub-docs/nginx.conf) as base for deploying your WireCloud infrastructure:
261+
This `docker-compose.yml` file requires configuring nginx, you can use [this `nginx.conf` file](https://github.com/Wirecloud/docker-wirecloud/blob/master/hub-docs/nginx.conf) as base for deploying your WireCloud infrastructure:
89262

90263
```nginx
91264
user nginx;
@@ -148,63 +321,33 @@ $ docker-compose up -d
148321
This docker-compose configuration will detect when the WireCloud configuration is missing and, in that case, it will populate the volume at `/opt/wirecloud_instance` (mapped to the local `wirecloud_instance` folder), the database and the `/var/www/static` volume (mapped to the local `static` folder). This initial configuration will not include any administrator user so, please create one using the `createsuperuser` command.
149322

150323

151-
### Running manage.py commands
152-
153-
You can run any available `manage.py` command by using `docker-compose exec wirecloud manage.py`. For example, you can create superusers/administrators by running the following command:
154-
155-
```
156-
$ docker-compose exec wirecloud manage.py createsuperuser
157-
Username (leave blank to use 'root'): admin
158-
Email address: ${youremail}
159-
Password: ${yourpassword}
160-
Password (again): ${yourpassword}
161-
Superuser created successfully.
162-
```
163-
164-
Regarding commands using the filesystem, take into account that those commands will be executed inside the container and thus the filesystem will be the one used by the container. The `manage.py` script will not check if those commands make changes outside the provided volumes. Anyway, they can be used without any problem. For example, static files can be collected using the following command:
165-
166-
```
167-
$ docker-compose exec wirecloud manage.py collectstatic
168-
```
169-
170-
Use `docker-compose exec wirecloud manage.py --help` for getting the list of available commands.
171-
172-
173-
### Customizations
174-
175-
The composable image uses two volumes, one for `/opt/wirecloud_instance` and another for `/var/www/static`. The only difference with the standalone image is that the static files are stored in `/var/www/static` instead of being stored in `/opt/wirecloud_instance/static`.
176-
177-
> **Note**: Rembember that any change made outside the defined volumes will be lost if the image is updated.
178-
179-
Composable images comes preloaded with some python modules to allow enabling extra functionalities. Those modules are:
180-
181-
- `python-social-auth`: Required to enable IdM configuration.
182-
- `pylibmc`: Required to use memcached.
183-
184-
185-
## License
324+
# License
186325

187326
View license information for [WireCloud](https://github.com/Wirecloud/wirecloud/blob/develop/LICENSE.txt).
188327

189-
## Supported Docker versions
328+
329+
# Supported Docker versions
190330

191331
This image is officially supported on Docker version 1.7.0.
192332

193333
Support for older versions (down to 1.0) is provided on a best-effort basis.
194334

195-
## User Feedback
196335

197-
### Documentation
336+
# User Feedback
337+
338+
## Documentation
198339

199340
This document should provide everything you need to install WireCloud using docker. Anyway, you can find the User & Programmer's Manual and the Administration Guides on [Read the Docs](https://wirecloud.readthedocs.io).
200341

201-
### Issues
342+
343+
## Issues
202344

203345
If you have any problems with or questions about this image, please contact us through a [GitHub issue](https://github.com/Wirecloud/docker-wirecloud/issues).
204346

205347
You can also reach many of the official image maintainers via the `fiware` and `fiware-wirecloud` tags on [StackOverflow](http://stackoverflow.com/questions/tagged/fiware-wirecloud).
206348

207-
### Contributing
349+
350+
## Contributing
208351

209352
You are invited to contribute new features, fixes, or updates, large or small; we are always thrilled to receive pull requests, and do our best to process them as fast as we can.
210353

‎latest-composable‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)