Custom Base Images
Replace Galaxy's default Docker base image with your own to control system packages and customize exactly what happens at build and run time.
By default, Galaxy builds your Meteor app using a standard base image that covers most use cases. But if you need full control over the system packages available to your app, or want to customize exactly what happens at build and run time, you can provide your own base image instead.
What you'll need: A Docker Hub account and a publicly readable Docker image
How It Works
When you run meteor deploy, your local Meteor CLI builds your app, bundles it into a tarball, and uploads it to Galaxy. Galaxy then builds a Docker image by running a setup script (/app/setup.sh) inside your base image using /bin/bash. After the build, Galaxy runs whatever command you define in your Dockerfile's CMD or ENTRYPOINT directive.
Your base image is a Docker image hosted on Docker Hub. It must be publicly readable, which means it should never contain secrets.
Setting Up a Custom Base Image
Write a Dockerfile
Start with a base OS (like ubuntu) and install the packages your app needs. You can look at the source of the Galaxy default base image for inspiration. You must also add a file called /app/setup.sh and specify a command to run with the CMD or ENTRYPOINT directives.
Galaxy passes a single argument to your setup script: a URL pointing to your app's tarball. Your script should download and expand that tarball. Here's a minimal example:
cd /app && curl -sS "$1" | tar xz -mThe -m flag ignores timestamps from the computer that ran meteor deploy. This avoids clock-skew issues in some build systems.
Your setup script can do anything else you need at build time: run npm install, invoke other build systems, etc.
Shell Requirement
Your image must include /bin/bash and /app/setup.sh. The setup script must have the executable bit set and a proper shebang line (like #!/bin/bash).
Push to Docker Hub
Build your image and push it to Docker Hub. Use a specific tag (like v23 or a git SHA) rather than a mutable tag like latest. Galaxy won't rebuild your app just because you pushed a new image to the same tag; a new deploy is always required.
docker build -t username/my-galaxy-base-image:v23 .
docker push username/my-galaxy-base-image:v23Use a new tag each time you update your base image. That way your settings.json reference is always explicit and you can roll back by changing the tag.
Configure settings.json
Tell Galaxy to use your image by adding a baseImage block inside the galaxy.meteor.com section of your settings.json:
{
"galaxy.meteor.com": {
"env": {
"MONGO_URL": "mongodb://..."
},
"baseImage": {
"repository": "username/my-galaxy-base-image",
"tag": "v23"
}
}
}The repository field should include your Docker Hub username. The tag field is the specific version you want to use.
Configure Your Deploy Method
How you apply the settings depends on how you deploy.
Push to Deploy (recommended): If you use Push to Deploy with Galaxy Mode, paste your complete settings.json content (including the baseImage block) into the Variables tab of your app. Galaxy stores and injects these settings on every deployment automatically. Just push your code and the custom base image is picked up.
CLI deploy: Pass your settings file directly with meteor deploy:
meteor deploy myapp --settings settings.jsonEither way, Galaxy will use your custom base image for this deployment and all future ones until you change the baseImage configuration.
Run Time Behavior
At run time, Galaxy invokes whatever command is specified in your Dockerfile's CMD or ENTRYPOINT directive. No additional arguments are passed.
Galaxy sets the environment variables documented under Container Environment.
Your command is expected to run a server that listens on the port specified by the $PORT environment variable. Galaxy needs to see a functioning web server to consider your app healthy. If you're deploying something that isn't a traditional web server (like a helper process for your main app), you should disable unhealthy container replacement on your app's settings page. That said, exposing a web server is recommended so you can tell whether your container is healthy.
Container Lifecycle
Your container runs until its specified command completes or Galaxy stops it.
Puppeteer Image
If your app uses Puppeteer for headless browser automation, there's a pre-built image that includes all the libraries Puppeteer needs. Configure it in your settings.json:
{
"galaxy.meteor.com": {
"env": {
"MONGO_URL": "mongodb://..."
},
"baseImage": {
"repository": "meteor/galaxy-puppeteer",
"tag": "latest"
}
}
}Galaxy Metal Compatibility
If the latest tag doesn't work on your app, try latest-2026 instead. That tag includes an updated image with full compatibility for Galaxy Metal.
When using this image, launch Puppeteer with these flags:
const browser = await puppeteer.launch({
args: [
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage'
]
});
const page = await browser.newPage();
await page.goto('https://www.google.com');These flags are required for Puppeteer to run correctly in Galaxy's container environment.
Common Questions
Need Help?
If you run into issues with custom base images, contact Galaxy support. Include your Docker Hub repository name and the error from your deploy logs.