- Write the dockerfile if there no suitale image for the application
- Write the docker-compose file and .env as per specifications
- Test it and pull request
Our specifications is very simple, you just only add the environments begin with APP_ reference from template
The architecture of the library is relatively simple, which is a collection of a large number of apps that are uniformly placed in the apps director. Each folder under apps is an independent and runnable Docker Compose project.
You can understand the basic composition and specifications through the Docker Compose template, The following points will help you quickly integrate into library project.
Try to use the official image as much as possible, unless there is no maintenance or updates have been stopped.
And you can also get image from public image hub:
The images used should be componentized as much as possible, with app main images and DB images, and web server images connected to achieve software availability.
All containers are placed on the network named websoft9, making them accessible to each other through container names.
We define all the names that need to be mounted at the end of docker-compose.yml and use them through references in different container.
Whether the container starts normally through Health check
The main container is named ${W9_ID}, and other containers add a suffix to ${W9_ID}, such as ${W9_ID}-mysql.When container connections cannot be adapted to the common rules above, there are two ways to correspond:
- Add hostname, named ${W9_RCODE}
- Container named servicename-${W9_RCODE}
Some application have lots of logs which will need storages. If you want to limit it, below is referance
wordpress:
image: wordpress:${W9_VERSION}
container_name: ${W9_NAME}
restart: unless-stopped
logging:
driver: "json-file"
options:
max-file: "5"
max-size: 10m
Suggest use the unified bind mount src which include config or script files for creating/modify application.
| file name | Description | Necessity |
|---|---|---|
| nginx-proxy.conf | nginx config code section which will insert to server{} by websoft9 api, and it can override the exist location | no |
| php_exra.ini | extra php.ini for PHP application, you can add it to docker-compose.yml if you want to use it | no |
you should add proxy_pass $forward_scheme://$server:$port$request_uri; to your nginx-proxy.conf if you override default location /{}
The Websoft9 platform reads this file as exactly
src/nginx-proxy.confand injects it into the Nginx Proxy Manager Proxy Hostserver{}block. It is not mounted into the app container, sodocker-compose.ymldoes not reference it. Only server-context directives belong here; http-context directives such aslimit_req_zone/limit_conn_zoneare defined platform-side and must not be declared in this file.
The environment variables of the container is the interface between the container and external interactions, the library all of the apps's environment variables are imported through .env file and cannot be directly defined in the docker-compose.yml, you can understand the basic composition and specifications through the .env template.
The environments begin with APP_ is core environment variables. Generally speaking, developers only define and use them.
For the canonical repository reference of W9_* variables, their decision rules, and common scenarios, read docs/w9-env-spec.md first.
Declare access port groups, default publishing toggles, and native public address/port mappings in variables.json.access per App Access Spec. Run libs app-check --app <app> --gate access and keep unverified evidence distinct from deployment results. Legacy access variables (W9_*_PORT_SET, W9_HTTP_PORT, W9_HTTPS_PORT, W9_URL, W9_URL_REPLACE, W9_ADMIN_PATH) are removed and rejected by validation.
We will list and explain commonly used environmental variables as following table:
| Variable name | Description | Necessity |
|---|---|---|
| W9_REPO | The main container docker image url | no |
| W9_DIST | The edition of main application | no |
| W9_VERSION | The version of this application, the image's tag of main container | yes |
| W9_POWER_PASSWORD | Original Password, all containers password in the Docker Compose are setted to this password, make all container passwords the same | no |
| W9_ID | The name of this application, main container also named by W9_ID |
yes |
| W9_LOGIN_USER | Application's login username | no |
| W9_LOGIN_PASSWORD | Application's login password | no |
| W9_ENCRYPT_PASSWORD | Some application must use password with encryption | no |
| W9_DB_EXPOSE | Main database of application | no |
| W9_NETWORK | We have uniformly created a network named constant websoft9, which ensures that multiple applications can easily access it through the container name if needed | yes |
main container: When the container has web pages, the corresponding container of the page is the main container; When a container has no pages, the corresponding container for the core application is usually the main container.
When we cannot find a suitable image, we have to compile the image by Dockerfile,We make a requirement in the following aspects.
The parent image needs to follow the following point:
- The preferred image is the one provided by the official, as the official image has undergone extensive testing and verification, and has good stability and reliability.
- Select the smallest possible base image to reduce the size of the image and potential security vulnerabilities.
- Select images that have undergone security review and frequent updates.
Main related files are all placed in two directories:
- root directory: Dockerfile, cmd.sh, entrypoint.sh
- src directory: config files or need to edit executable files
Sufficient external interfaces need to be provided through environment variables, such as username,passowrd,port.
The elements of label are necessary: such as version,vendor,description.
Configure files use src to mount to container
- Docker official image or Bitnami image have different method for php configuration
- Docker official image need mount php_exra.ini to container
- Bitnami image have envs of php configuration
- As a reference, other php application should check if php conf.d directoy exist in container, mount php_exra.ini to this path
Every application must contain a variables.json, which contains information such as version, trademark, document reference address, and running environment requirements.
Record some important items to remind all contributors.
Change logs. Use a pure-date heading ## YYYY-MM-DD as the first-level heading for each change batch, with a bullet list of changes below it.
Create a new application with libs app-new from metadata/templates/new-app/, then set your files:
- docker-compose.yml
- Docker image address using environment variables
- Do not expose external ports in the main database and message queue of web applications
- Each container must directly reference. env
- Use after declaring volumes
- The configuration file volumes uses the absolute path reference of src
- Do not write upstream reference comments in docker-compose.yml; upstream references live only in
variables.jsonupstream - Every published port line must carry an inline
# purposecomment, e.g.- "9001:80" # Web Console
- .env
- Custom environment variables start with W9
- Place the environment variables of the container itself last of .env
- Users configure published ports through the
accessgroups, not.envaliases. - These variables must be included in .env: W9_REPO, W9_DIST, W9_VERSION, W9_ID
- Do not add
W9_*_PORT_SET,W9_HTTP_PORT,W9_HTTPS_PORT,W9_URL,W9_URL_REPLACEorW9_ADMIN_PATH; declare host ports, public URLs and admin paths invariables.json.accessand map upstream native variables throughrootUrl/host/mappedPort - Keep the container listener and the default host mapping literal in
docker-compose.yml; do not reuse one variable for both sides of the mapping - The user's main database type is W9_ DB_ EXPOSE to determine
You know there three type container for an application:
- Application container
- Application assisting container: Which help application container for automatic install wizard, monitor...
- Independent Service: e.g database, mq, redis
We suggest add Application container and Application assisting container 's environments to .env
- Prefer
x.xtags forW9_VERSIONwhen the upstream image publishes a stablex.xtag. - Use
x.x.xonly when the upstream image does not provide a usablex.xtag, or when an exact patch pin is required for compatibility, migration safety, or a known upstream regression. - Do not use prerelease tags unless the issue explicitly targets prerelease testing.