Skip to content

Commit f16e928

Browse files
sabmeuaNyholm
sabmeua
and
Nyholm
authored
Add docs for create new extension layer #14 (#17)
* Add docs for create new extension layer #14 * Improve documents * Remove redundant sentence * Adding some minor fixes Co-authored-by: Tobias Nyholm <[email protected]>
1 parent 1bf69ae commit f16e928

File tree

2 files changed

+210
-0
lines changed

2 files changed

+210
-0
lines changed

‎Readme.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,8 @@ be in their "standard" location.
9191
3. Update .travis.yml to include your extension
9292
4. Update the table in the readme
9393

94+
Please refer [here](docs/create_your_own_extension_layer.md) for more details.
95+
9496
### Deploy new versions
9597

9698
```

‎docs/create_your_own_extension_layer.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# How to build new layer
2+
3+
To create your own extension layer, compile the extension and any required libraries
4+
with Docker. This guide uses pgsql extension as an example.
5+
6+
First create new extension directory in `layers/` and move there.
7+
8+
```bash
9+
$ mkdir layers/pgsql && cd $_
10+
```
11+
12+
Create `Dockerfile` such as follows.
13+
14+
```Dockerfile
15+
ARG PHP_VERSION
16+
FROM bref/build-php-$PHP_VERSION AS ext
17+
18+
#
19+
# Add commands to build PHP extensions here.
20+
#
21+
22+
# Build the final image from the lambci image that is close to the production environment
23+
FROM lambci/lambda:provided
24+
25+
#
26+
# Add commands to copy files that requried for final image.
27+
#
28+
```
29+
30+
The environment variable `PHP_VERSION` is passed from the Makefile as an argument
31+
to docker build. It may have values like: `72`, `73`, `74`. A docker image is created
32+
for each PHP_VERSION. If the build procedure of your extension differs for each version,
33+
you may use this variable to switch processing in Dockerfile.
34+
35+
There are some other env variables available,`PHP_BUILD_DIR` is `/tmp/build/php`, `INSTALL_DIR` is `/opt/bref`.
36+
37+
### Building your extension
38+
39+
Then you need to add two parts of Dockerfile, the following snippets are examples
40+
of build and copy parts respectively.
41+
42+
```Dockerfile
43+
44+
WORKDIR ${PHP_BUILD_DIR}/ext/pgsql
45+
RUN phpize
46+
RUN ./configure --with-pgsql=${INSTALL_DIR}
47+
RUN make -j `nproc` && make install
48+
49+
RUN cp `php-config --extension-dir`/pgsql.so /tmp/pgsql.so
50+
```
51+
52+
You may need to:
53+
- download the source code,
54+
- install the libraries required for compilation,
55+
- perform pecl install,
56+
- etc.
57+
58+
The Dockerfiles for [these](../layers) extensions could be very helpful.
59+
60+
### Copy files
61+
62+
63+
The extension layer consists of a zip archive of files that overlay the PHP layer,
64+
so copy the files and create the layer file structure here. Extension and all related
65+
files that need to be installed should be placed `/opt` directory in the final image.
66+
Because only `/opt` directory is allowed to put things in Lambda custom runtime
67+
environment.
68+
69+
```Dockerfile
70+
COPY --from=ext /tmp/pgsql.so /opt/bref-extra/pgsql.so
71+
```
72+
73+
### Making a layer
74+
75+
It might be good to build extension step-by-step and create Dockerfile from command
76+
history instead of immediately building from Dockerfile.
77+
78+
```bash
79+
$ docker run -it bref/build-php-$PHP_VERSION /bin/bash # Run build environment with ”-it” option and build the extension step by step.
80+
```
81+
82+
Once you have created Dockerfile, make sure the build succeeds.
83+
84+
```bash
85+
$ make docker-images
86+
```
87+
88+
If the build goes through, generate zip files of the layers in `export/` directory.
89+
90+
```bash
91+
$ make layer
92+
```
93+
94+
Register the zip file generated above to AWS as Lambda Layer. It also able to add from AWS console.
95+
96+
```bash
97+
$ aws lambda publish-layer-version --layer-name pgsql-php-73 --zip-file fileb://./export/layer-pgsql-php-73.zip
98+
```
99+
100+
# How to test layers
101+
102+
Create a Bref App for testing. The usage of `bref` and `serverless`, please refer [here](https://bref.sh/docs/installation.html).
103+
104+
```bash
105+
$ mkdir pgsql-test-app && $_
106+
$ composer init
107+
## Everything OK for default.
108+
$ composer require bref/bref
109+
$ vendor/bin/bref init
110+
What kind of lambda do you want to create? (you will be able to add more functions later by editing `serverless.yml`) [PHP function]:
111+
[0] PHP function
112+
[1] HTTP application
113+
[2] Console application
114+
> 1
115+
## Select suitable for check your extension.
116+
```
117+
118+
In `serverless.yml`, edit `region` and add layer ARN which you added earlier.
119+
120+
```diff
121+
service: app
122+
123+
provider:
124+
name: aws
125+
- region: us-east-1
126+
+ region: <YOUR AWS REGION>
127+
runtime: provided
128+
129+
plugins:
130+
- ./vendor/bref/bref
131+
132+
functions:
133+
api:
134+
handler: index.php
135+
description: ''
136+
timeout: 28 # in seconds (API Gateway has a timeout of 29 seconds)
137+
layers:
138+
- ${bref:layer.php-73-fpm}
139+
+ - arn:aws:lambda:<YOUR AWS REGION>:<YOUR AWS ID>:layer:pgsql-php-73:3
140+
141+
events:
142+
- http: 'ANY /'
143+
- http: 'ANY /{proxy+}'
144+
```
145+
146+
Update `index.php` to be allowed you to check the extension.
147+
148+
```diff
149+
<?php
150+
151+
- echo "Hello World";
152+
+ #
153+
+ # Add some check processing
154+
+ #
155+
```
156+
157+
Add a setting to load the extension.
158+
159+
```bash
160+
$ mkdir -p php/conf.d
161+
$ echo "extension=/opt/bref-extra/pgsql.so" > php/conf.d/pgsql.ini
162+
```
163+
164+
Finally deploy and test this function.
165+
166+
```bash
167+
$ serverless deploy
168+
```
169+
170+
# Prepare for contribution
171+
172+
Contributions to add new extensions are welcomed. When you built new extension, please contribute it by all means.
173+
In order to contribute, you should do a little more work.
174+
175+
* Make sure that it works with each PHP versions in the way described above
176+
* Update the document and CI settings as follows
177+
178+
Update the table in the `Readme.md` in alphabetical order.
179+
180+
```diff
181+
### Available layers
182+
183+
| Name | Serverless config (php 7.4) | php.ini config |
184+
| ---- | ----------------------------| -------------- |
185+
| AMQP | `${bref:extra.amqp-php-74}` | `extension=/opt/bref-extra/amqp.so` |
186+
| Blackfire | `${bref:extra.blackfire-php-74}` | `extension=/opt/bref-extra/blackfire.so` |
187+
| GMP | `${bref:extra.gmp-php-74}` | `extension=/opt/bref-extra/gmp.so` |
188+
| Memcache | `${bref:extra.memcached-php-74}` | `extension=/opt/bref-extra/memcache.so` |
189+
| Memcached | `${bref:extra.memcached-php-74}` | `extension=/opt/bref-extra/memcached.so` |
190+
+| PostgreSQL | `${bref:extra.pgsql-php-74}` | `extension=/opt/bref-extra/pgsql.so` |
191+
| Xdebug | `${bref:extra.xdebug-php-74}` | `zend_extension=/opt/bref-extra/xdebug.so` |
192+
193+
Note that the "Memcached" layer provides both extension for [Memcache](https://pecl.php.net/package/memcache) and [Memcached](https://pecl.php.net/package/memcached).
194+
```
195+
196+
Update `.travis.yml` as follows.
197+
198+
```diff
199+
env:
200+
- LAYER=amqp PHP="72 73 74"
201+
- LAYER=blackfire PHP="72 73 74"
202+
- LAYER=gmp PHP="72 73 74"
203+
- LAYER=memcached PHP="72 73 74"
204+
+ - LAYER=pgsql PHP="72 73 74"
205+
- LAYER=xdebug PHP="72 73 74"
206+
```
207+
208+
Once you have done above please submit the PR.

0 commit comments

Comments
 (0)