Run SMILE with Docker Compose

Docker Compose is the lightweight way to run the full SMILE stack on a single machine, for example to try it locally or run a small private instance. It needs less setup than Kubernetes but doesn't scale out. For production deployments, see Deploy SMILE on Kubernetes with Helm.

All images are prebuilt and published on Docker Hub, so you only need the compose files and your own configuration.

What gets started

Service	Purpose	Port
smile-server	The SMILE web application	8001
smile-graphql	Data server that queries the social media platform APIs	5050
rabbitmq	Message broker between SMILE and the analysis containers	5672, management UI on 15672
minio	S3-compatible storage for collected data and analysis results	9000, console on 9001
redis	Stores users' platform credentials in multi-user mode	6379
algorithm-*, image-crawler, collect-reddit-comment	One container per analysis, each listening on its own RabbitMQ queue	none
nginx, certbot	HTTPS reverse proxy with Let's Encrypt certificates, for public servers	80, 443

The AWS Lambda and AWS Batch boxes in the diagram are only used when LOCAL_ALGORITHM=false. With the default LOCAL_ALGORITHM=true, every analysis runs in its local container.

1. Install Docker and get the compose files

1. Install Docker by following https://docs.docker.com/get-docker/.

2. Some analyses are memory-intensive. In Docker Desktop, open Settings → Resources and give Docker as much memory and CPU as you can spare (8 GB of memory or more is a good starting point), staying below your machine's total.

3. Clone the deployment repository and go to the SMILE compose directory:

   git clone https://github.com/ncsa/smm-deployment.git
   cd smm-deployment/docker/smile

   The files you need are:

   • docker-compose-smile.yml, the main stack.
   • docker-compose-smile-clowder.yml, an optional add-on for exporting results to Clowder.
   • config.txt, the image version for each component. Edit it to upgrade individual components.
   • docker-command-smile.sh, a template that sets every environment variable and starts the stack.

2. Configure the environment

Make a copy of docker-command-smile.sh (for example my-smile.sh, kept out of version control because it will contain secrets) and fill in the values.

System settings

Variable	What to set
SERVER	An address of the host machine that the containers can reach: its IP address for a local install (macOS: ipconfig getifaddr en0, Linux: hostname -I), or its domain name on a server. Do not use localhost, because inside a container that refers to the container itself. MINIO_URL, RABBITMQ_URL and SMILE_GRAPHQL_URL are built from it.
HOME	A directory on the host for persistent data. The script creates smile_data/, smile_user/ and smile/ inside it.
SINGLE_USER	true for a personal install: there is no login, and everything is stored under your OS user name. false enables multi-user login through CILogon, which needs the CILOGON_* variables below.
LOCAL_ALGORITHM	Leave as true so analyses run in the local containers.
AWS_ACCESSKEY, AWS_ACCESSKEYSECRET	Despite the names, these become the MinIO root user and password. Choose your own random values (MinIO requires at least 3 and 8 characters respectively).
BUCKET_NAME	The storage bucket name. The default macroscope-smile is fine.

Login (only if SINGLE_USER=false): register an OIDC client at CILogon and set CILOGON_CLIENT_ID, CILOGON_CLIENT_SECRET, and CILOGON_CALLBACK_URL (http://<SERVER>:8001/smile-login/callback).

Social media sources. Configure only the platforms you want to collect from:

Platform	Variables	Where to get credentials
Reddit	REDDIT_ON, REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, REDDIT_CALLBACK_URL	https://www.reddit.com/prefs/apps
Twitter / X	TWITTER_ON, TWITTER_V2_CLIENT_ID, TWITTER_V2_CLIENT_SECRET, TWITTER_V2_CALLBACK_URL	https://developer.x.com (API access is paid and restricted)
YouTube, Google Drive	GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_CALLBACK_URL	https://console.cloud.google.com

Set REDDIT_ON=false or TWITTER_ON=false to hide a platform you don't configure.

Exporting results (optional): BOX_CLIENT_ID/BOX_CLIENT_SECRET, DROPBOX_CLIENT_ID/DROPBOX_CLIENT_SECRET, and the Google variables above.

Email notifications (optional): long-running analyses email users their results when they finish. Set EMAIL_HOST, EMAIL_PORT, EMAIL_FROM_ADDRESS, and EMAIL_PASSWORD to enable this. If they are unset, SMILE doesn't ask users for an email address.

Clowder add-on (optional): set CLOWDER_ON=true, CLOWDER_BASE_URL, and CLOWDER_GLOBAL_KEY. The template currently spells the first one CLOWSER_ON, so correct it if you enable Clowder.

3. Decide whether you need nginx

The nginx and certbot services provide HTTPS for a public server. They build from an ./nginx directory that isn't in smm-deployment; it lives in standalone-smm-analytics/containerized_analytics/smile/nginx.

• Local install: delete or comment out the nginx and certbot services in docker-compose-smile.yml. You'll reach SMILE directly on port 8001.
• Public server: copy that nginx directory next to the compose file and adjust nginx.conf for your domain.

4. Start SMILE

The last lines of the template start the stack. Make sure the start command reads:

docker compose -f docker-compose-smile.yml up -d
# or, with the Clowder add-on:
# docker compose -f docker-compose-smile.yml -f docker-compose-smile-clowder.yml up -d

Then run your script with bash. It uses source, which plain sh doesn't support on every system:

bash my-smile.sh

When the containers are up, open http://<SERVER>:8001. The MinIO console is on port 9001 and the RabbitMQ management UI is on port 15672.

Day-to-day operations

The docker compose commands below read your configuration from the environment, so export the variables first (for example, run source my-smile.sh with its start line commented out).

Task	Command
Stop	docker compose -f docker-compose-smile.yml down
See logs	docker compose -f docker-compose-smile.yml logs -f smile-server
Update images	Bump the tags in config.txt, then docker compose -f docker-compose-smile.yml pull and start again
Remove the Docker volumes	docker compose -f docker-compose-smile.yml down -v

The volumes are bind mounts, so your data stays in $HOME/smile_data, $HOME/smile_user and $HOME/smile even after down -v. Delete those directories to wipe it.

Troubleshooting

• Searches fail with ECONNREFUSED 127.0.0.1:5050: SERVER (and therefore SMILE_GRAPHQL_URL) is set to localhost. Use the host's IP address instead.
• Analyses hang or containers restart: check docker compose logs <service>. Memory-hungry analyses such as topic modeling and AutoPhrase may need more memory allocated to Docker.
• Download links don't open: MINIO_PUBLIC_ACCESS_URL must be reachable from the user's browser, not just from the containers.