doclink_web/INSTALLATION_UBUNTU.md

DocLink Web Installation Guide for Ubuntu

This guide explains how to run doclink_web on Ubuntu behind Apache, using a subfolder URL such as:

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:

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:

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:

sudo nano /etc/doclink-web.env

Example content:

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:

sudo nano /etc/systemd/system/doclink-web.service

Example content:

[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:

sudo systemctl daemon-reload
sudo systemctl enable doclink-web
sudo systemctl start doclink-web

Check status:

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:

export DOCLINK_BASE_PATH=/docklink-desktop
export PORT=5173
node server.js

If you prefer the helper script:

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:

sudo a2enmod proxy proxy_http ssl
sudo systemctl restart apache2

7. Configure Apache Virtual Host

Create or edit your site config in:

sudo nano /etc/apache2/sites-available/domain.conf

Example configuration:

<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:

sudo a2ensite domain.conf
sudo systemctl reload apache2

9. Verify the Deployment

Open the application in the browser:

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:

./stop.sh

Or stop a specific port:

./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:

  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