Table of Contents
MetaPloy is just a containerized nginx reverse proxy that acts as the main web server (ingress server) for all metakgp projects. It exposes a Docker network named metaploy-network and a volume named metaploy-nginx-config-volume. The volume is mounted at /etc/nginx/sites-enabled/ and reads .metaploy.conf files that contain the nginx configurations for each of the individual projects.
Each project hosted on the server is containerized and connected to the metaploy-network, and its nginx configuration file is copied to the metaploy-nginx-config-volume volume. MetaPloy watches for changes in the volume and reloads the configuration if any changes are made (e.g., a new project is loaded or unloaded).
These config files are included inside the top-level http directive and should contain only the server directives. See the usage section for examples.
Docker and docker compose are the only required dependencies. You can either install Docker Desktop or the Docker Engine. For minimal installations and server use cases, Docker Engine is recommended.
- Clone this repository.
- Copy the contents of the
.env.templatefile into the.envfile. Create the file if it doesn't exist. - Set the
SERVER_PORTvariable to the desired port. This is the port at which the server will be accessible on the system. - Run
docker compose upto start MetaPloy.
MetaPloy uses docker networks and volumes for its core functionality. See docker-compose.yml for the definitions. There are two main networks and one volume:
- The
metaploy-networkwhich is used for connecting projects to the ingress server. Anything on this network can be exposed to the external world via the ingress server. - The
nginx-config-volumewhich contains the nginx configuration files for each project and is mounted at/etc/nginx/sites-enabled. - The
metaploy-private-networkwhich is not exposed to the ingress server. It is used for internal communication between different projects connected to metaploy. Eg: For a database to be accessed by multiple projects.
MetaPloy listens to changes in the config directory using watch_reload.sh. If any file is changed, a new one is added, or removed (such as during the starting or stopping of a project), the nginx configuration is reloaded using nginx -s reload. All configuration files inside the configuration directory are directly included under the http directive of the ingress server. See the last lines of nginx.conf.
To connect a project to a running MetaPloy instance, the following is required:
- Add the metaploy networks and volumes in the project's docker compose file (or connect to the network in any other way).
- Create a
[project].metaploy.conffile that adds directives to connect to the server and sets the server directives including theserver_nameto set the domain. See example. - Copy the config file to the config volume when the project starts. This can be done by running a postinstall script as the entrypoint of the container.
See the example. Also see existing projects using metaploy:
- IQPS Backend - Uses the standard template described here. Also uses the private network to connect to a database and file server.
- Metakgp Wiki - A non-standard legacy example with an nginx proxy of its own that uses fastcgi.
- Odin's Vault: A static file server that exposes a volume internally and a file server externally.
- Database of Babel: A Postgres database that only uses the private network and does not expose anything outside.
Sometimes we have to debug things out in production environment. To make this process streamlined there is an auto reload script running as a background service which checks for any changes made to nginx configurations (/etc/nginx/nginx.conf and /etc/nginx/sites-enabled/*) and reloads nginx automatically. Check out the script here. In case you need to debug the script itself you can check-out the logs in the docker container located at /nginx_auto_reload_service.log.
📫 Metakgp -
