You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/0-getting-started/03-docker.md
+38-38Lines changed: 38 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,13 +5,13 @@ description: Tempest can both be developed or deployed in Production, with our o
5
5
6
6
## Overview
7
7
8
-
We are pleased to offer TempestPHP/Aloft, our own set of Docker images for developing with and serving your Tempest applications, for you to use as and customise as you see fit.
8
+
We are pleased to offer our own set of Docker images for developing with and serving your Tempest applications, for you to use as and customise as you see fit.
9
9
10
10
In order to start from the strongest security posture and enable you to run secure and performant Tempest-based applications, we've initially selected FrankenPHP as our server of choice. Further, we've adopted a 'rootless' approach by default, and also offer a 'distroless' production image to further mitigate potential security issues stemming from unnecessary software often found in Docker images.
11
11
12
-
## Aloft image architecture, variants and release strategy
12
+
## Image architecture, variants and release strategy
13
13
14
-
Our CI/CD will automatically generate and publish images to our public repository at https://PLACE.HOLD.ER/tempestphp/aloft following the releases of PHP and FrankenPHP, and also any time we find an issue in the underlying Docker image. Alternatively, you can also customise these images for your own use, see section below. (TODO: link)
14
+
Our CI/CD will automatically generate and publish images to our public repository at https://PLACE.HOLD.ER/tempestphp/ship following the releases of PHP and FrankenPHP, and also any time we find an issue in the underlying Docker image. Alternatively, you can also customise these images for your own use, see section below. (TODO: link)
15
15
16
16
### Architectures
17
17
@@ -25,13 +25,13 @@ We maintain two variants; 'latest' which is rootless and distroless, and is aime
25
25
26
26
```bash
27
27
# These periodically updated variant tags will always point at the latest version-pinned images
28
-
tempestphp/aloft>> tempestphp/aloft:1.11.3-8.5.3 #at time of writing
29
-
tempestphp/aloft:latest >> tempestphp/aloft:1.11.3-8.5.3 #at time of writing
30
-
tempestphp/aloft:debug >> tempestphp/aloft:1.11.3-8.5.3-debug #at time of writing
28
+
tempestphp/ship>> tempestphp/ship:1.11.3-8.5.3 #at time of writing
29
+
tempestphp/ship:latest >> tempestphp/ship:1.11.3-8.5.3 #at time of writing
30
+
tempestphp/ship:debug >> tempestphp/ship:1.11.3-8.5.3-debug #at time of writing
31
31
32
32
# We'll also continually publish pinned-versions
33
-
tempestphp/aloft:1.11.3-8.5.3
34
-
tempestphp/aloft:1.11.3-8.5.3-debug
33
+
tempestphp/ship:1.11.3-8.5.3
34
+
tempestphp/ship:1.11.3-8.5.3-debug
35
35
# these will accumulate over time
36
36
```
37
37
We utilise the [GoogleContainerTools Distroless](https://github.com/GoogleContainerTools/distroless/)[`cc`](https://github.com/GoogleContainerTools/distroless/blob/main/cc/README.md) image, pulling their latest 'nonroot' image as our base, at time of build.
@@ -52,83 +52,83 @@ We won't automatically retire 'patch' version releases i.e. PHP8.5.3 > PHP8.5.4,
52
52
53
53
## Developing your application with Docker
54
54
55
-
During development, we'd suggest using the debug image. We've included a convenience command in the `tempest/aloft` package which will run a development server on your device.
55
+
During development, we'd suggest using the debug image. We've included a convenience command in the `tempest/ship` package which will run a development server on your device.
56
56
```bash
57
-
./tempest aloft:serve # by default, this will get debug from the repository and serve it
57
+
./tempest ship:serve # by default, this will get debug from the repository and serve it
58
58
```
59
59
You may specify the `latest` image if you prefer.
60
60
```bash
61
-
./tempest aloft:serve latest # latest floating version
61
+
./tempest ship:serve latest # latest floating version
62
62
```
63
63
You may instead specify the release, if you require a pinned-version.
By default, the `aloft:serve` command will try to pull from the registry. But if you have published the stub for customising the image, this command will attempt to use the local image. You can force this behaviour by adding the optional command `--repository=local` or `--repository=remote`.
70
+
By default, the `ship:serve` command will try to pull from the registry. But if you have published the stub for customising the image, this command will attempt to use the local image. You can force this behaviour by adding the optional command `--repository=local` or `--repository=remote`.
71
71
:::
72
72
73
73
## Testing and production applications with Docker
74
74
75
75
For testing and QA, we'd suggest using the distroless image, as it is most representative of your final infrastructure, and should highlight any issues for your attention.
76
76
```bash
77
-
./tempest aloft:serve latest
77
+
./tempest ship:serve latest
78
78
```
79
79
As per the section above, you can omit `latest` to default to the `debug` release, or specify a version.
80
80
81
81
## Customising the Docker image for your use
82
82
83
-
As the `latest` and `debug` images are inherently distroless, albeit with busybox in the `debug` image, you cannot use this as an intermediate stage in a multi-stage Dockerfile build. Instead, you can use the `aloft:publish` Tempest command to publish a copy of the stubs, so you can build and tweak as you need.
83
+
As the `latest` and `debug` images are inherently distroless, albeit with busybox in the `debug` image, you cannot use this as an intermediate stage in a multi-stage Dockerfile build. Instead, you can use the `ship:publish` Tempest command to publish a copy of the stubs, so you can build and tweak as you need.
84
84
```bash
85
-
./tempest aloft:publish # by default, this will publish the debug dockerfile
86
-
./tempest aloft:publish:latest # select the distroless image, instead
85
+
./tempest ship:publish # by default, this will publish the debug dockerfile
86
+
./tempest ship:publish:latest # select the distroless image, instead
87
87
```
88
88
This will publish `.dockerignore`, `Caddyfile`, and `Dockerfile` into your project root `docker/` folder, creating it as necessary. If you already have files in here, it shouldn't overwrite by default.
89
89
90
90
You can also retrieve the files manually, from the vendor folder.
91
91
```bash
92
-
vendor/tempest/framework/packages/aloft/stubs/
92
+
vendor/tempest/framework/packages/ship/stubs/
93
93
```
94
94
### Building the image
95
95
96
-
We've provided a simple `aloft:build` command to build these local images. It won't handle all use cases, and is really only aimed at someone directly running the images. If you are ready to change the Dockerfile to suit your needs, you probably won't want to use this anyway. That said, here's how to use it.
96
+
We've provided a simple `ship:build` command to build these local images. It won't handle all use cases, and is really only aimed at someone directly running the images. If you are ready to change the Dockerfile to suit your needs, you probably won't want to use this anyway. That said, here's how to use it.
97
97
98
98
If you HAVE NOT published the stubs to your project:
99
99
```bash
100
-
./tempest aloft:build # will attempt to build debug directly from the package stubs folder
101
-
./tempest aloft:build debug # will attempt to build debug directly from the package stubs folder
102
-
./tempest aloft:build latest # will attempt to build distroless directly from the package stubs folder
100
+
./tempest ship:build # will attempt to build debug directly from the package stubs folder
101
+
./tempest ship:build debug # will attempt to build debug directly from the package stubs folder
102
+
./tempest ship:build latest # will attempt to build distroless directly from the package stubs folder
103
103
```
104
104
If you HAVE published the stubs to your project:
105
105
```bash
106
-
./tempest aloft:build # will attempt to build debug from `{root_path}/docker/`
107
-
./tempest aloft:build debug # will attempt to build debug from `{root_path}/docker/`
108
-
./tempest aloft:build latest # will attempt to build distroless from `{root_path}/docker/`
106
+
./tempest ship:build # will attempt to build debug from `{root_path}/docker/`
107
+
./tempest ship:build debug # will attempt to build debug from `{root_path}/docker/`
108
+
./tempest ship:build latest # will attempt to build distroless from `{root_path}/docker/`
109
109
```
110
110
:::info
111
-
If you've published both stubs, or renamed the Dockerfile, this won't work. You've moved past the use-case this command was designed for, and will need to build yourself. Or copy the AloftBuildCommand into your project and customise it to suit you!
111
+
If you've published both stubs, or renamed the Dockerfile, this won't work. You've moved past the use-case this command was designed for, and will need to build yourself. Or copy the ShipBuildCommand into your project and customise it to suit you!
112
112
:::
113
113
114
114
### Default versions of FrankenPHP and PHP
115
115
116
116
We will update the stubs from time-to-time, but you may find that your PHP and/or FrankenPHP versions are out of step, because you have customised your file and don't wish to republish the stubs losing the changes.
117
117
118
-
You can use the `aloft:build` command to pass the arguments:
118
+
You can use the `ship:build` command to pass the arguments:
To retain compatibility with `aloft:serve` ensure that the image retains `tempestphp/aloft:`and then pass `1.11.3-8.5.3` as the image variant i.e. `./tempest aloft:serve 1.11.3-8.5.3`.
131
+
To retain compatibility with `ship:serve` ensure that the image retains 'tempestphp/ship:' in the filename and then pass `1.11.3-8.5.3` as the image variant i.e. `./tempest ship:serve 1.11.3-8.5.3`.
This method also retains compatibility with `aloft:serve` and `aloft:build`, as long as you keep the filename unchanged.
140
+
This method also retains compatibility with `ship:serve` and `ship:build`, as long as you keep the filename unchanged.
141
141
:::
142
142
143
143
## Adding additional PHP Extensions
144
144
145
145
We include PHP Extensions from [Marc Henderkes'](https://pkgs.henderkes.com/) Static PHP Repository. These are static builds, of PHP-ZTS, which is required by FrankenPHP.
146
146
147
147
:::info
148
-
Note that apt-get packages are kebab-case and should be prefixed `php-zts`. So if you wanted the extension `pdo_mysql`, you'd specify `php-zts-pdo-mysql`.
148
+
Note that apt-get packages are kebab-case and should be prefixed `php-zts`. So if you wanted the extension `pdo_mysql`, you'd specify `php-zts-pdo-mysql`. The command won't convert the syntax automatically.
149
149
:::
150
150
151
151
### Adding extensions at build time via build arguments
@@ -154,11 +154,11 @@ This method is useful if you need to make a specific build one-off, containing a
154
154
155
155
Pass the build argument directly if using a published stub Dockerfile:
This will work with both the `debug` and `latest` images.
@@ -195,7 +195,7 @@ We suggest one of the following options instead.
195
195
196
196
You can use the following command to run composer interactively:
197
197
```bash
198
-
docker run --rm -i --tty --volume $PWD:/app --user 1002:1002 composer:latest # We suggest running with 1002:1002 to match the file permissions within our rootless image
198
+
docker run --rm -i --tty --volume $PWD:/app --user 1002:1002 composer:latest # We suggest running with 1002:1002 to match the file permissions within our rootless images
$this->console->info('Stubs are published, and you are using the local repository, therefore ensure that you run aloft:build before using aloft:serve');
65
+
$this->console->info('Stubs are published, and you are using the local repository, therefore ensure that you run ship:build before using ship:serve');
0 commit comments