Skip to content

Commit 3af05e7

Browse files
zamronypjzamronypj
committed
reorganize directory structure for deployment documentation
1 parent 4d4e49c commit 3af05e7

File tree

6 files changed

+236
-196
lines changed

6 files changed

+236
-196
lines changed

‎deployment/cgi/index.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: Deploy as CGI application
3+
description: Tutorial on how to deploy CGI web application built with Fano Framework to various web servers.
4+
---
5+
6+
<h1 class="major">Deployment as CGI application</h1>
7+
8+
### Apache
9+
10+
This section explains how to deploy web application as CGI application on Apache web server.
11+
12+
#### Dedicated server
13+
14+
This section explains how to deploy server that you have full control and administrative privilege (aka root access).
15+
16+
##### Debian-based Linux
17+
18+
- Create virtual host by adding Apache configuration file inside `/etc/apache2/sites-available` and put
19+
20+
```
21+
<VirtualHost *:80>
22+
ServerAdmin [[server administrator email]]
23+
ServerName [[fano application hostname]]
24+
25+
DocumentRoot "[[/path/to/fano/app/public]]"
26+
27+
<Directory "[[/path/to/fano/app/public]]">
28+
Options -MultiViews +ExecCGI
29+
AllowOverride FileInfo Indexes
30+
Require all granted
31+
AddHandler cgi-script .cgi
32+
DirectoryIndex app.cgi
33+
</Directory>
34+
</VirtualHost>
35+
```
36+
37+
Replace `[[server administrator email]]` with administrator email for example, if we use domain name `fano.dev` we can use `admin@fano.dev`.
38+
39+
Replace `[[fano application hostname]]` with domain that we use,
40+
for example in this case, it is `fano.dev`. So when Apache receive request with URI http://fano.dev/test it will match
41+
this virtual host entry and call our application.
42+
43+
44+
Replace `[[/path/to/fano/app/public]]` with directory where our application binary reside. If you store it outside Apache
45+
document root directory, you need to specify with with `<Directory>`.
46+
47+
For example, if we store application binary in directory `/home/myuser/myapp/public` which outside Apache document root, we need to
48+
add `Require` directive to allow Apache to serve request from
49+
this directory, otherwise they will be rejected.
50+
51+
Above snippet basically tells Apache to allow (`+ExecCGI`) to serve any file ends with `cgi` extension as CGI script (`AddHandler cgi-script .cgi`). `-MultiViews` also important to disable automatic content negotiation because we need to add URL rewriting to allow use of routing in our application. So Our application will be responsible to decide what response to return.
52+
53+
So in our example, we end up with following configuration:
54+
55+
```
56+
<VirtualHost *:80>
57+
ServerAdmin admin@fano.dev
58+
ServerName fano.dev
59+
60+
DocumentRoot "/home/myuser/myapp/public"
61+
62+
<Directory "/home/myuser/myapp/public">
63+
Options -MultiViews +ExecCGI
64+
AllowOverride FileInfo Indexes
65+
Require all granted
66+
AddHandler cgi-script .cgi
67+
DirectoryIndex app.cgi
68+
</Directory>
69+
</VirtualHost>
70+
```
71+
72+
You need to make sure that `app.cgi` has execution bit, if not then run
73+
74+
```
75+
$ chmod 744 /home/myuser/myapp/public/app.cgi
76+
```
77+
For most uses-cases, `744` permission is suffice if your web server is run as your user account. If executable binary failed to run, try `774`
78+
79+
Save it as `fano.conf` file. Note that saving data to `/etc/apache2/sites-available` directory requires administrative privilege.
80+
81+
- Enable virtual host
82+
83+
To make our virtual host active, put symlink in `/etc/apache2/sites-enabled` that points to `/etc/apache2/sites-available/fano.conf`.
84+
85+
```
86+
$ sudo ln -s /etc/apache2/sites-available/fano.conf /etc/apache2/sites-enabled/fano.conf
87+
```
88+
or you can use `a2ensite` utility that comes with Debian distribution which does same thing.
89+
90+
```
91+
$ sudo a2ensite fano.conf
92+
```
93+
94+
- Restart Apache service
95+
96+
```
97+
$ sudo service apache2 restart
98+
```
99+
100+
If configuraton is ok, Apache will restart happily.
101+
102+
- Setup domain name to DNS
103+
104+
If you have not register a domain name with domain name registrar, you can setup fake domain name for local development only by adding
105+
entry to `/etc/hosts` file. Open `/etc/hosts` and add following entry,
106+
107+
```
108+
127.0.0.1 fano.dev
109+
```
110+
111+
`127.0.0.1` with assumption that Apache run on same machine.
112+
113+
##### Fedora-based Linux
114+
115+
#### Shared-hosting
116+
117+
This section explains how to deploy server that you have no full control and have very limited administrative privelege.
118+
119+
##### Debian-based Linux
120+
121+
##### Fedora-based Linux
122+
123+
##### CPanel-based server
124+
125+
### Nginx
126+
127+
This section explains how to deploy web application as CGI application on Nginx web server.

‎deployment/continous-integration/index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Deploy Fano application with Continous Integration tools
3+
description: Tutorial on how to deploy Fano application with CI.
4+
---
5+
6+
<h1 class="major">Deploy Fano application with Continous Integration tools</h1>
7+
8+
## Jenkins
9+
10+
## TravisCI

‎deployment/docker/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: Deploy Fano application inside Docker container
3+
description: Tutorial on how to deploy Fano application with Docker container.
4+
---
5+
6+
<h1 class="major">Deploy Fano application inside Docker container</h1>

‎deployment/fastcgi/index.md‎

Lines changed: 82 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,95 @@ description: Tutorial on how to deploy FastCGI web application built with Fano F
55

66
<h1 class="major">Deployment as FastCGI application</h1>
77

8+
## Apache
89

9-
## Deploy as FastCGI application
10+
Currently, to deploy as FastCGI application you can only deploy with
11+
[mod_proxy_fcgi](https://httpd.apache.org/docs/2.4/mod/mod_proxy_fcgi.html)
1012

11-
### Apache
13+
You need to have `mod_proxy_fcgi` installed and loaded. This module is Apache's built-in module, so it is very likely that you will have it with your Apache installation. You just need to make sure it is loaded.
1214

13-
### Nginx
15+
### Debian
1416

17+
For example, on Debian,
1518

16-
## Deploy as standalone web server
19+
```
20+
$ sudo a2enmod proxy_fcgi
21+
$ sudo systemctl restart apache2
22+
```
1723

24+
Create virtual host config and add `ProxyPassMatch`, for example
1825

19-
## Deploy using Docker
26+
```
27+
<VirtualHost *:80>
28+
ServerName www.example.com
29+
DocumentRoot /home/example/public
2030
21-
## Deployment with Continous Integration tools
31+
<Directory "/home/example/public">
32+
Options +ExecCGI
33+
AllowOverride FileInfo
34+
Require all granted
35+
</Directory>
2236
23-
### Jenkins
37+
ProxyRequests Off
38+
ProxyPass /css !
39+
ProxyPass /images !
40+
ProxyPass /js !
41+
ProxyPassMatch ^/(.*)$ fcgi://127.0.0.1:20477
42+
</VirtualHost>
43+
```
44+
You may need to replace `fcgi://127.0.0.1:20477` with hostname and port where your
45+
application is running.
2446

25-
### Travis CI
47+
Last four line of virtual host configurations basically tell Apache to serve any
48+
files inside `css`, `images`, `js` directly otherwise pass it to our application.
49+
50+
On Debian, save it to `/etc/apache2/sites-available` for example as `fano-fastcgi.conf`
51+
Enable this site and restart Apache
52+
53+
```
54+
$ sudo a2ensite fano-fastcgi.conf
55+
$ sudo systemctl restart apache2
56+
```
57+
58+
#### Use unix domain socket
59+
60+
If your Fano application and Apache run on same machine, you can get small improvement by using unix domain socket file. See example [Fano Fastcgi Unix application](https://github.com/fanoframework/fano-fcgi-unix).
61+
62+
If application is listening using socket file `/tmp/fano-fcgi.sock`, you need to change `ProxyPassMatch` as follows:
63+
64+
```
65+
ProxyPassMatch ^/(.*)$ "unix:/tmp/fano-fcgi.sock|fcgi://127.0.0.1/"
66+
```
67+
Note that `|fcgi://127.0.0.1/` is required so `mod_proxy_fcgi` is called to handle request eventhough host and port information are ignored.
68+
69+
#### Socket file permission issue
70+
71+
You need to make sure that `/tmp/fano-fcgi.sock` is writeable by Apache.
72+
73+
If you run with something like
74+
75+
```
76+
$ ./bin/app.cgi
77+
```
78+
`/tmp/fano-fcgi.sock` file will be own by user where above command is executed. It will cause permission denied for Apache user.
79+
80+
For development stage, easy solution is just change owner of file. After application is bound and listen, you may want to open another
81+
shell and execute
82+
83+
```
84+
$ sudo chown [your current user]:www-data /tmp-fano-fcgi.sock
85+
```
86+
where `www-data` is user which Apache runs.
87+
88+
Using `/tmp` also may cause problem if you run Debian 9 - based distribution (such as Ubuntu 18.04). Since Debian 9 (Stretch), by default each user has private /tmp directory. So if you run application as current user, `/tmp/fano-fcgi.sock` will not be found by Apache which run as different user.
89+
90+
Proper way is setup application to run as service, set socket file to `/var/run` and set group which service run, add Apache user into that group. Then you can
91+
just run application using
92+
93+
```
94+
systemctl start [your-app-service-name]
95+
```
96+
97+
98+
99+
## Nginx

0 commit comments

Comments
 (0)