Xitmer Documentation
Services
Services are individual projects or applications that you nomarlly build or run. In Xitmer all such projects or applications are called as services which could be eaither a standalone application like a website or part of a project like a backend Node API or a frontend Angular application.
Service Files
To define various details of an application like its repository, image, environments, etc. service files are used. By default a service file named services-default.json is available in the services folder inside the data directory when you install the software.
You can modify and define your application details in the default services file under the services array attribute using options given below.
| Option | Description |
|---|---|
| name | Name of the service. |
| image | The base image which will be used to create the container where the code will be run. |
| cic | Set this option to true if the code is to be placed and run from within the container instead of the host system. Code repository option need to be specified for this to work. |
| dir | The directory on the host system where code of the application is available. This is not used if cic option is set to true. |
| dev_url | The url using which you want the service to be accessible in the browser of your development system. If not specified the url will be the same as the name of the service and accessible at https:\\service_name.xit. |
| srv_port | The container port that the service will use when run in the container. |
| serving_location | A string value to be used for setting the location parameter of the nginx host configuration. Generally you won't need to use this as by default all services will listen for the \ path in the URL. |
| rep | To specify the code repository options viz. remote, slug, wb. The remote option takes a SCM key set in the SCM configuration section of the config.json file. The slug option is the slug part of the repository after the SCM domain name like username/my-app.git. The wb option is used to set the working branch name that will be checkedout to run/develop the application. |
| env | This option can be used to specify different environments like staging, production, etc. and their access details where the application will run. The available options for an env is given seprately later in the document. |
| wd | The path in the container where the code of the application will be available |
| dep | List of dependecy files available in the codebase like composer.json, package.json, etc. which will be run when starting the application. |
| type | To specify type of the application like web or console |
| command | The command that will be run for starting the application, e.g. npm run dev |
| mnt | An array of object pairs like {"src":"D:\\Code\\source_path", "dst":"/var/www/my-code"} which will be mounted as volumes to the container. The src attribute specifies the path in the host system that will be mounted to the path in the container specified by the dst attribute. |
| disabled | Set this to true if you want to disable the service so that it doesn't start whenever the start services command is used. |
The content of an example service definition file is given below for reference.
{
version:1,
services:[
{
"name": "my_app",
"type": "web",
"dir": "D:\\Code\\my_app",
"srv_port": 80,
"image": "php:7.4-apache",
"wd": "/var/www/html",
"dep": [],
"repo": {
"remote": "github",
"slug": "username/my-dpp.git",
"wb": "master"
},
"env": {
"prod": {
"code_dir": "/var/www/my-app",
"conn": {
"ssh": {
"host": "xxx.xxx.xxx.xxx",
"port": "xx",
"user": "ssh_user",
"key": ">sshd/ssh_key_file_name"
}
}
}
}
}
]
}
Service Environments
In the above example service definition in the env section an environment named prod has been defined. The code_dir option there specifies where the code is stored in the environment and the conn attribute specifies available connection options like SSH.
In the ssh option the key attribute specifies the path to the key file which will be used for authentication. You may notice that for the key path a special notation >sshd has been used. This notation simply translates to the user's .ssh folder path in the host machine. Alternatively you can also use the full absolute path if you like instead of the short notation.
Service Groups
You can also create your own service files to specify groups of related services of a project or even groups of unrelated services. To do this you just need to create another json file in the services folder in the format services-group_name.json where group_name is the name of your service group. The service definitions in these files are same as described before.
Starting the services
Once you have defined a service as appropriate, either in the default services file or in any other service file, you can issue the following command to start the service:
xit start service name_of_the_service
Simillarly to stop the service you can issue the following command:
xit stop service name_of_the_service
You can add multiple services to the services-default.json file and if you wish to start them all at once then you can issue the following command instead of starting each service individually one by one:
xit start services
Simillarly, to start all the services defined in a service group file you will need to use a command in the following format:
xit start services group_name
To view all the available services from all the service definition files you can use the following command:
xit list services
To stop all running services all at once you can use the following command:
xit down
The down command basically removes all running service containers and clears any entries made to the hosts file of the host system.
There is also a xit up command available that starts all the defined services in all the service definition files (except for services which has disable attribute set to false). The up command may be suitable if you have a small number of projects or if you have enough resources on the host system.