Add base-path deployment support
This commit is contained in:
sas.fajri
246
INSTALLATION_UBUNTU.md
Normal file
246
INSTALLATION_UBUNTU.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# DocLink Web Installation Guide for Ubuntu
|
||||
|
||||
This guide explains how to run `doclink_web` on Ubuntu behind Apache, using a subfolder URL such as:
|
||||
|
||||
```text
|
||||
https://domain.com/docklink-desktop
|
||||
```
|
||||
|
||||
## 1. Requirements
|
||||
|
||||
- Ubuntu Server
|
||||
- Apache 2
|
||||
- Node.js 18+ or compatible
|
||||
- A valid SSL certificate if you want HTTPS
|
||||
|
||||
## 2. Copy the Application
|
||||
|
||||
Place the project on the server and enter the project directory:
|
||||
|
||||
```bash
|
||||
cd /path/to/doclink_web
|
||||
```
|
||||
|
||||
Make sure these files exist:
|
||||
|
||||
- `server.js`
|
||||
- `styles.css`
|
||||
- `logo.png`
|
||||
- `start.sh`
|
||||
- `stop.sh`
|
||||
|
||||
## 3. Install Apache on Ubuntu
|
||||
|
||||
Update package lists and install Apache:
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y apache2
|
||||
```
|
||||
|
||||
If Node.js is not installed yet, install the version you want to use on the server.
|
||||
|
||||
## 4. Create the systemd Service
|
||||
|
||||
The app should run as a service so it starts automatically and keeps running in the background.
|
||||
|
||||
Create an environment file, for example:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/doclink-web.env
|
||||
```
|
||||
|
||||
Example content:
|
||||
|
||||
```bash
|
||||
DOCLINK_BASE_PATH=/docklink-desktop
|
||||
PORT=5173
|
||||
DOCLINK_API_BASE=https://devbandungraya.aplikasi.web.id/one-api-doctor/doctor_mitra
|
||||
```
|
||||
|
||||
Then create the service file:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/doclink-web.service
|
||||
```
|
||||
|
||||
Example content:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=DocLink Web
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
WorkingDirectory=/path/to/doclink_web
|
||||
EnvironmentFile=/etc/doclink-web.env
|
||||
ExecStart=/usr/bin/node /path/to/doclink_web/server.js
|
||||
Restart=on-failure
|
||||
RestartSec=3
|
||||
User=www-data
|
||||
Group=www-data
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Reload systemd and enable the service:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable doclink-web
|
||||
sudo systemctl start doclink-web
|
||||
```
|
||||
|
||||
Check status:
|
||||
|
||||
```bash
|
||||
sudo systemctl status doclink-web
|
||||
```
|
||||
|
||||
## 5. Run the Application Manually
|
||||
|
||||
This step is optional. Use it only if you want to test the app without systemd.
|
||||
|
||||
Run it directly:
|
||||
|
||||
```bash
|
||||
export DOCLINK_BASE_PATH=/docklink-desktop
|
||||
export PORT=5173
|
||||
node server.js
|
||||
```
|
||||
|
||||
If you prefer the helper script:
|
||||
|
||||
```bash
|
||||
DOCLINK_BASE_PATH=/docklink-desktop PORT=5173 ./start.sh
|
||||
```
|
||||
|
||||
Important notes:
|
||||
|
||||
- `DOCLINK_BASE_PATH` must match the public URL path.
|
||||
- The local project folder name can be anything.
|
||||
- Apache will forward requests to the Node.js app on `127.0.0.1:5173`.
|
||||
|
||||
## 6. Enable Apache Modules
|
||||
|
||||
Enable the required proxy and SSL modules:
|
||||
|
||||
```bash
|
||||
sudo a2enmod proxy proxy_http ssl
|
||||
sudo systemctl restart apache2
|
||||
```
|
||||
|
||||
## 7. Configure Apache Virtual Host
|
||||
|
||||
Create or edit your site config in:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/apache2/sites-available/domain.conf
|
||||
```
|
||||
|
||||
Example configuration:
|
||||
|
||||
```apache
|
||||
<VirtualHost *:80>
|
||||
ServerName domain.com
|
||||
Redirect permanent / https://domain.com/
|
||||
</VirtualHost>
|
||||
|
||||
<VirtualHost *:443>
|
||||
ServerName domain.com
|
||||
|
||||
SSLEngine on
|
||||
SSLCertificateFile /path/to/fullchain.pem
|
||||
SSLCertificateKeyFile /path/to/privkey.pem
|
||||
|
||||
ProxyPreserveHost On
|
||||
ProxyRequests Off
|
||||
|
||||
RedirectMatch 301 ^/docklink-desktop$ /docklink-desktop/
|
||||
|
||||
ProxyPass /docklink-desktop/ http://127.0.0.1:5173/
|
||||
ProxyPassReverse /docklink-desktop/ http://127.0.0.1:5173/
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
If you want a reusable deployment template, start from:
|
||||
|
||||
- `deploy/apache-vhost.template.conf`
|
||||
- `deploy/env.template`
|
||||
|
||||
Then replace:
|
||||
|
||||
- `__SERVER_NAME__`
|
||||
- `__BASE_PATH__`
|
||||
- `__APP_PORT__`
|
||||
- `__SSL_CERT_FILE__`
|
||||
- `__SSL_KEY_FILE__`
|
||||
|
||||
## 8. Enable the Site
|
||||
|
||||
Enable the site and reload Apache:
|
||||
|
||||
```bash
|
||||
sudo a2ensite domain.conf
|
||||
sudo systemctl reload apache2
|
||||
```
|
||||
|
||||
## 9. Verify the Deployment
|
||||
|
||||
Open the application in the browser:
|
||||
|
||||
```text
|
||||
https://domain.com/docklink-desktop/
|
||||
```
|
||||
|
||||
If everything is configured correctly, the application should load without exposing port `5173` publicly.
|
||||
|
||||
## 10. Stop the Application
|
||||
|
||||
If you started the app with the helper script:
|
||||
|
||||
```bash
|
||||
./stop.sh
|
||||
```
|
||||
|
||||
Or stop a specific port:
|
||||
|
||||
```bash
|
||||
./stop.sh 5173
|
||||
```
|
||||
|
||||
## 11. Ubuntu-Specific Locations
|
||||
|
||||
- Apache site configs:
|
||||
- `/etc/apache2/sites-available/`
|
||||
- `/etc/apache2/sites-enabled/`
|
||||
- Apache logs:
|
||||
- `/var/log/apache2/access.log`
|
||||
- `/var/log/apache2/error.log`
|
||||
- Apache service commands:
|
||||
```bash
|
||||
sudo systemctl status apache2
|
||||
sudo systemctl restart apache2
|
||||
sudo systemctl reload apache2
|
||||
```
|
||||
|
||||
## 12. Troubleshooting
|
||||
|
||||
### The page does not open
|
||||
|
||||
- Check that the `doclink-web` service is running
|
||||
- Check that the Node.js app is listening on `127.0.0.1:5173`
|
||||
- Check that Apache modules `proxy` and `proxy_http` are enabled
|
||||
- Confirm that `DOCLINK_BASE_PATH=/docklink-desktop`
|
||||
|
||||
### CSS or logo does not load
|
||||
|
||||
- Confirm requests are going through `/docklink-desktop/...`
|
||||
- Check the Apache proxy configuration for the correct trailing slash
|
||||
|
||||
### Redirects go back to `/`
|
||||
|
||||
- Make sure every public request uses the same base path
|
||||
- Keep `DOCLINK_BASE_PATH` aligned with the URL folder
|
||||
Reference in New Issue
Block a user