Development Stuff for hardware and software configurations
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

266 lines
10 KiB

3 years ago
  1. # dubsdot
  2. Adding or modifying dubsdot services are relatively easy. Please make sure that you don't interrupt other services on this shared hosts. Also, **DO NOT** run services from an LDAP user; use a local account if the service can't be run as the `nobody` or `www-data` user. Please request help if you are having problems. Also, **DO NOT EVER** directly edit the `/etc/apache2/apache2.conf` file without prior permission! Use sites-available folders with separate files for each service instead **PLEASE**. Also, don't declare things in the global scope of your configuration files, only within your `VirtualHost` definitions.
  3. # Sections
  4. * Putting your application in place
  5. * Configuring your service with Apache
  6. * Configuring Virtual Hosts
  7. * Connecting your application to Dubsdot
  8. * Static site with no backend
  9. * Dynamic site with backend
  10. * Alternative backend server or other complex configuration
  11. * Control Access
  12. ## Putting your application in place
  13. It is **very** discouraged to run applications out of your LDAP folder, and rather to create yourself a folder in `/var/www` where you can run your application from. If the application does not actually use a website directory served by Apache, you can alternatively create a folder in `/opt` to store your custom socket application.
  14. For example, if your project is called "FancyApp", you can
  15. ```
  16. git clone https://github.com/<gh username>/FancyApp.git
  17. ```
  18. while in the /var/www folder, and it will create the `/var/www/FancyApp` folder in the correct directory with your code within that folder.
  19. ## Configuring your service with Apache
  20. Your web service probably should be integrating with the webserver in one of a few select ways. No matter what, you have to interface with the currently running webserver. Right now, that's Apache 2, although we plan to move to nginx in the near future to make it easier to handle configuring applications, as well as much increased performance.
  21. (fun fact: Apache performs way worse than nginx at the same tasks)
  22. ## Configuring Virtual Hosts
  23. In all cases, you will be setting up a new CNAME record on the DNS server to point at Dubsdot. (feel free to ask for help with this) For example, you may add a line like this to the BIND server:
  24. ```
  25. myservice IN CNAME dubsdot
  26. ```
  27. Basically, what this means is that if the DNS server receives queries for `myservice.cslabs.clarkson.edu`, your computer will be directed to connect to the server dubsdot, located at `dubsdot.cslabs.clarkson.edu` with an IP address of 128.153.145.200, and use a host value of `myservice.cslabs.clarkson.edu`. You should also, however, configure your virtual hosts to listen on `myservice.cosi.clarkson.edu`, as well as `myservice`, since you also want it to work when we use domain name search on the local machines (you may have been told to go to `fsu/` in the past, for example), as well as when you connect from our other domain name(s).
  28. ## Connecting your application to Dubsdot
  29. There are a few different ways that you can configure your service on Dubsdot
  30. * Set up a directory, and service html/css/js for a website with no backend
  31. * Set up a directory, and run PHP or other code and html/css/js for a website with a backend
  32. * Configure a separate service to handle requests on a different port, and redirect these requests through Apache 2 using a reverse proxy. This works for more complicated applications, and can be connected in various different ways.
  33. ### Static site with no backend
  34. **Use this configuration if you are only serving static files.**
  35. To configure your static website with no backend, clone your website to `/var/www/<myapp>`, as seen above. For example, while in the `/var/www` folder, run:
  36. ```bash
  37. git clone https://github.com/<username>/<myapp>.git
  38. ```
  39. and it will clone your app to `/var/www/myapp`.
  40. Once it does that, become root on the system, and run the following:
  41. ```
  42. cd /etc/apache2/sites-available
  43. ```
  44. Create a new file called `<myapp>.conf` in this folder.
  45. ```
  46. vim <myapp>.conf
  47. ```
  48. Inside that, add some content like this:
  49. ```
  50. # Service: myapp
  51. <VirtualHost *:80>
  52. DocumentRoot "/var/www/myapp"
  53. ServerName myapp.cslabs.clarkson.edu
  54. ServerAlias myapp.cosi.clarkson.edu
  55. ServerAlias myapp
  56. </VirtualHost>
  57. ```
  58. Here's the explanation of the various parts of the above configuration:
  59. * `VirtualHost *:80`: Listen on port 80 on any IP(v4?) address
  60. * `DocumentRoot "/var/www/myapp"`: Set the document location root to `/vrestore the file from a backup.ar/www/myapp`. Say that you have a file called `index.html` at `/var/www/myapp/index.html`, with the value set here, you will find your `index.html` at `http://myapp.cslabs.clarkson.edu/index.html`
  61. * `ServerName myapp.cslabs.clarkson.edu`: Sets the default server name to listen for when specified by your browser from DNS with the `Host:` HTTP field.
  62. * `ServerAlias myapp.cosi.clarkson.edu`: Additional server names to listen for on the website, if they mach, you will get directed here the same way as with `ServerName`. This field is optional, `ServerName` is not.
  63. Of these, the first and last opening/closing `VirtualHost`, `DocumentRoot`, and `ServerName` are required entries.
  64. **ALLWAYS** have the configuration contained within the `VirtualHost` tags. **DO NOT** put options outside of these! It **WILL** negatively affect other services.
  65. After you have created your file, feel free to run the following as root (they will fail to auto-complete if you are not a root shell because stupid):
  66. Enable the website:
  67. ```
  68. a2ensite myapp
  69. ```
  70. Test the configuration:
  71. ```
  72. apachectl configtest
  73. ```
  74. If it fails, run the following so that if the server is rebooted for other reasons, that it doesn't crash the server:
  75. ```
  76. a2dissite myapp
  77. ```
  78. Once you feel confident with the configuration file you have specified, feel free to run the following:
  79. ```
  80. systemctl restart apache2
  81. ```
  82. If your service brings down the apache server, please disable your site.
  83. ### Dynamic site with backend
  84. **Use this configuration if you are doing PHP or something like that.**
  85. **TODO**
  86. ### Alternative backend server
  87. **Use this configuration if you are using Flask or a custom socket server.**
  88. To configure your static website with a TCP socket backend, clone your website to `/var/www/<myapp>`, as seen above, and your application code to `/opt/<myapp>`. For example, while in the `/var/www` folder, run:
  89. ```bash
  90. git clone https://github.com/<username>/<myapp>.git
  91. ```
  92. and it will clone your app to `/var/www/myapp`.
  93. Once you finish all of that, become root on the system, and run the following:
  94. ```
  95. cd /etc/apache2/sites-available
  96. ```
  97. Create a new file called `<myapp>.conf` in this folder.
  98. ```
  99. vim <myapp>.conf
  100. ```
  101. Inside that, add some content like this:
  102. ```
  103. # Service: myapp
  104. <VirtualHost *:80>
  105. ServerName myapp.cslabs.clarkson.edu
  106. ServerAlias myapp.cosi.clarkson.edu
  107. ServerAlias myapp
  108. DocumentRoot "/var/www/myapp"
  109. ProxyPreserveHost on
  110. ProxyPass /api http://localhost:99999
  111. ProxyPassReverse /api http://localhost:99999
  112. </VirtualHost>
  113. ```
  114. Here's the explanation of the various parts of the above configuration:
  115. * `VirtualHost *:80`: Listen on port 80 on any IP(v4?) address
  116. * `DocumentRoot "/var/www/myapp"`: Set the document location root to `/vrestore the file from a backup.ar/www/myapp`. Say that you have a file called `index.html` at `/var/www/myapp/index.html`, with the value set here, you will find your `index.html` at `http://myapp.cslabs.clarkson.edu/index.html`
  117. * `ServerName myapp.cslabs.clarkson.edu`: Sets the default server name to listen for when specified by your browser from DNS with the `Host:` HTTP field.
  118. * `ServerAlias myapp.cosi.clarkson.edu`: Additional server names to listen for on the website, if they mach, you will get directed here the same way as with `ServerName`. This field is optional, `ServerName` is not.
  119. * `ProxyPreserveHost on`: Preserve hostname in queries while passing to socket.
  120. * `ProxyPass /api http://loclahost:99999`: Pass the `/api` url (and all below it) to the proxy specified
  121. * `ProxyPassReverse /api http://localhost:99999`: erm. It's important!
  122. Of these, the first and last opening/closing `VirtualHost`, `DocumentRoot`, and `ServerName` are required entries.
  123. **ALLWAYS** have the configuration contained within the `VirtualHost` tags. **DO NOT** put options outside of these! It **WILL** negatively affect other services.
  124. After you have created your file, feel free to run the following as root (they will fail to auto-complete if you are not a root shell because stupid):
  125. Enable the website:
  126. ```
  127. a2ensite myapp
  128. ```
  129. Test the configuration:
  130. ```
  131. apachectl configtest
  132. ```
  133. If it fails, run the following so that if the server is rebooted for other reasons, that it doesn't crash the server:
  134. ```
  135. a2dissite myapp
  136. ```
  137. Once you feel confident with the configuration file you have specified, feel free to run the following:
  138. ```
  139. systemctl restart apache2
  140. ```
  141. If your service brings down the apache server, please disable your site.
  142. Please note that you will also need to make a systemd service to run your socket application, and that it is highly discouraged to run it in tmux or otherwise.
  143. **TODO:** Add systemd instructions here for a new service.
  144. **TODO:** Add information about using Unix sockets with Flask apps.
  145. ## Control Access
  146. Say you want your application to be visible only within Clarkson University.
  147. Modify what you have in your `Location` directive to something like this:
  148. ```
  149. <Location />
  150. Order deny,allow
  151. Deny from all
  152. Allow from 128.153.0.0/16
  153. </Location>
  154. ```
  155. To further restrict to COSI, use `Allow from 128.153.144.0/23` in replacement for the other `Allow` statement. You can also add additional `Allow` (or `Deny`) entries as needed to the end, for example, for a single IPv4 address, do `Allow from 128.153.145.200/32`.
  156. Here's a more complicated example with multiple subfolders:
  157. ```
  158. # root of website
  159. <Location />
  160. Order deny, allow
  161. Deny from all
  162. # allow from Clarkson
  163. Allow from 128.153.0.0/16
  164. </Location>
  165. <Location /private>
  166. Order deny, allow
  167. Deny from all
  168. # allow from only within COSI
  169. Allow from 128.153.144.0/23
  170. </Location>
  171. <Location /veryprivate>
  172. Order deny, allow
  173. Deny from all
  174. # allow from one particular computer (ex, dubsdot)
  175. Allow from 128.153.145.200/32
  176. # add another
  177. Allow from 128.153.145.201/32
  178. Allow from 128.153.145.202/32
  179. </Location>
  180. ```