Skip to content

Uguu Configuration & Installation

Jump to bottom Edit New page
Go Johansson (neku) edited this page Jun 14, 2025 · 47 revisions

Information

For submitting issues visit Uguu on Github.

Requirements

Software

  • Debian 11 or newer
  • Nginx
  • PHP/PHP-FPM-8.3 (if PHP8.3 is missing you can add the Sury PHP repo by following this this guide)
  • Git
  • SQLite3 (also supports MySQL & PostgreSQL)
  • Bun

Installation

Packages

Start off by installing the following packages:

apt-get install build-essential pngquant nginx-full php8.3-fpm php8.3 sqlite3 php8.3-sqlite3 \
php8.3-curl unzip git php8.3-cli php8.3-opcache php8.3-apcu \
php8.3-mcrypt php8.3-mysql php8.3-pgsql php8.3-zip \
php8.3-common php8.3-readline php8.3-bcmath php8.3-common php8.3-xml

Install Bun:

curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

Domain and SSL certificate

We will not cover how to obtain and setup a domain and certificate. However I'd recommend buying a domain on a website like Dynadot and get SSL certificates using Acme.sh.

Paths

Assuming you are using the following paths for various things, if they don't exist you should create them.

mkdir /var/www
mkdir /var/www/uguu
mkdir /var/www/db
mkdir /var/www/files
  • Uguu: /var/www/uguu
  • Uploaded files: /var/www/files
  • Database: /var/www/db

Download Uguu, setup the database and set permissions

Run this command to clone the Uguu Github and move the files to the correct folders, or do it yourself (I don't care).

cd /var/www/uguu/
git clone https://github.com/nokonoko/Uguu .

Now let's setup the database, run this command:

sqlite3 /var/www/db/uguu.sq3 -init /var/www/uguu/src/static/dbSchemas/sqlite_schema.sql ""

Then set the correct permissions so Nginx, PHP and SQLite can do their thing.

chown www-data:www-data /var/www/db
chown www-data:www-data /var/www/db/uguu.sq3
chown www-data:www-data /var/www/files
chmod -R 775 /var/www

Nginx example configuration

We won't cover settings everything up, here are some Nginx examples.

Main Domain

server {
    listen            443 ssl http2;
    server_name       dev.uguu.se;

    ssl on;
    ssl_certificate   /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    ssl_protocols     TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-CCM:DHE-RSA-AES256-CCM8:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-CCM:DHE-RSA-AES128-CCM8:DHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256';
    ssl_prefer_server_ciphers on;
    ssl_session_tickets off;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:10m;
    ssl_buffer_size 4k;

    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 1.1.1.1 8.8.8.8 valid=300s;
    resolver_timeout 5s;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    root              /var/www/uguu/dist/public/;
    autoindex         off;
    access_log        off;
    index index.html  index.php;
    etag              on;

    location ~* \.(css|js|jpg|jpeg|gif|png|ico|xml|eot|woff|woff2|ttf|svg|otf|x-icon|avif|webp|apng|gz|avif)$ {
      expires         30d;
    }

    gzip_static  always;
    gzip_proxied expired no-cache no-store private auth;
    gunzip       on;
    gzip         off;

    rewrite ^(/.*)\.html(\?.*)?$ $1$2 permanent;
    rewrite ^/(.*)/$ /$1 permanent;

    location /robots.txt {
     try_files $uri $uri/;
    }

    location / {
      try_files $uri/index.html $uri.html $uri/ @extensionless-php;
    }

    location @extensionless-php {
      rewrite ^(.*)$ $1.php last;
    }

    location ~* \.php$ {
    try_files $uri =404;
    fastcgi_pass     unix:/var/run/php/php8.3-fpm.sock;
    fastcgi_intercept_errors on;
    fastcgi_index    index.php;
    fastcgi_split_path_info ^(.+\.php)(.*)$;
    include          fastcgi_params;
    fastcgi_param    SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}
server {
    listen           80;
    server_name      dev.uguu.se;
    access_log       off;
    return 301       https://dev.uguu.se$request_uri;
  }

Subdomain serving uploaded files (do not enable PHP here)

server {
    listen           443 ssl;
    server_name      files.dev.uguu.se;

    ssl              on;
    ssl_certificate  /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    ssl_protocols    TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-CCM:DHE-RSA-AES256-CCM8:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-CCM:DHE-RSA-AES128-CCM8:DHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256';
    ssl_prefer_server_ciphers on;
    ssl_session_tickets off;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:10m;
    ssl_buffer_size 16k;

    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 1.1.1.1 8.8.8.8 valid=300s;
    resolver_timeout 5s;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    root             /var/www/files/;
    autoindex        off;
    access_log       off;
    index            index.html;
    etag             on;
  }
server {
    listen           80;
    server_name      files.dev.uguu.se;
    access_log       off;
    return 301       https://files.dev.uguu.se$request_uri;
  }

Serve everything off one domain (no subdomain for files)

server {
    listen           443 ssl;
    server_name      dev.uguu.se;
    ssl              on;
    ssl_certificate  /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    ssl_protocols    TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-CCM:DHE-RSA-AES256-CCM8:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-CCM:DHE-RSA-AES128-CCM8:DHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256';
    ssl_prefer_server_ciphers on;
    ssl_session_tickets off;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:10m;
    ssl_buffer_size 16k;

    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 1.1.1.1 8.8.8.8 valid=300s;
    resolver_timeout 5s;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    root             /var/www/uguu/dist/public/;
    autoindex        off;
    access_log       off;
    index index.html index.php;

    location ~* \.(css|js|jpg|jpeg|gif|png|ico|xml|eot|woff|woff2|ttf|svg|otf|x-icon|avif|webp|apng|gz|avif)$ {
    expires          30d;
    }

    location ^~ /files/ {
     alias           /var/www/files/;
     index           index.html index.htm;
     autoindex       off;
     include         mime.types;
     types {
      text/plain     php;
    }
  }

    gzip_static  always;
    gzip_proxied expired no-cache no-store private auth;
    gunzip       on;
    gzip         off;

    rewrite ^(/.*)\.html(\?.*)?$ $1$2 permanent;
    rewrite ^/(.*)/$ /$1 permanent;

    location /robots.txt {
     try_files $uri $uri/;
    }

    location / {
      try_files $uri/index.html $uri.html $uri/ @extensionless-php;
    }

    location @extensionless-php {
      rewrite ^(.*)$ $1.php last;
    }

    location ~* \.php$ {
    try_files $uri =404;
    fastcgi_pass     unix:/var/run/php/php8.3-fpm.sock;
    fastcgi_intercept_errors on;
    fastcgi_index    index.php;
    fastcgi_split_path_info ^(.+\.php)(.*)$;
    include          fastcgi_params;
    fastcgi_param    SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
  }
server {
    listen           80;
    server_name      dev.uguu.se;
    access_log       off;
    return 301       https://dev.uguu.se$request_uri;
  }

General Nginx configuration

You will need to increase client_max_body_size in nginx.conf to the max file upload size (e.g 128M which is the same as 128MB).

PHP-FPM Configuration

Edit /etc/php/8.3/fpm/php.ini and change the settings post_max_size and upload_max_filesize.

  • upload_max_filesize defines the max size a file is allowed to be, so in this case set this to 128M.
  • post_max_size defines how much data we can send in a single POST, setting this to 256M should be fine (128M * 2).

No further configuration should be needed for PHP.

Restarting services

Now we just need to restart some services in order to load the new configuration.

service nginx restart
service php8.3-fpm restart

Uguu Configuration and installation

Ejs Templates

You may edit the files inside src/templates to your liking.

config.json

This configuration file contains settings for the site, do not remove or move it.

It should be located at /var/www/uguu/src/config.json

  • pages what pages to compile from the templates.
  • DEBUG shows errors beyond the "servers error" message, should only be enabled for debugging and not in production.
  • BENCHMARK_MODE should be set to false when not benchmarking, otherwise file(s) will not be uploaded.
  • max_upload_size default is 128, the max file size which an user can upload in MB. Be sure this matches the PHP/Nginx configuration.
  • expireTime e.g 24, if the below value is set to hours this will mean 24 hours before files expire.
  • expireTimeUnit can be set to seconds, minutes, hours, days, weeks, months or years.
  • siteName the name of your site, e.g Uguu. This will appear in the browser title and on several places on the website.
  • subTitle site subtitle, e.g temporary file hosting
  • DOMAIN the URL to your site e.g dev.uguu.se
  • FILE_DOMAIN the URL of the subdomain serving the uploaded files, e.g files.dev.uguu.se. If you are using Uguu without a subdomain to serve files this should also include the path to the files under the same domain without an extra forward slash, e.g dev.uguu.se/files.
  • abuseContact the email dedicated to receive abuse reports, this can be the same as infoContact if you want. Make sure it's a valid email or else you run the risk of getting into trouble from your server provider.
  • infoContact the email dedicated to receive general email from users.
  • ServerCountryLocation the country your server is located in, this is related to abuse/DMCA since it often depends on local laws.
  • SiteMetaInfo a description of your site, search engines show this data in searches for your site.
  • responseTime e.g "24 hours", will be shown in the FAQ for your take down response time.
  • showGithub true/false, if the Github link to this repo should show up in the nav bar.
  • donationBanner true/false depending if you want to compile the donation banner.
  • paypalUrl the URL to your Paypal donation page. This can be ignored if the donations banner isn't enabled, or if you don't want to enable that method of donating.
  • bitcoinAddress your Bitcoin address for donations. This can be ignored if the donations banner isn't enabled. or if you don't want to enable that method of donating.
  • ethereumAddress your Ethereum address for donations. This can be ignored if the donations banner isn't enabled. or if you don't want to enable that method of donating.
  • kofiUrl your Ko-Fi donation URL. This can be ignored if the donations banner isn't enabled. or if you don't want to enable that method of donating.
  • malwareBanner true/false depending if you want to compile the malware banner.
  • DB_MODE set this to sqlite, mysql or pgsql depending on the database you're gonna use.
  • DB_PATH path to your database e.g /var/www/db/uguu.sq3 (SQLite), unix_socket=/var/run/mysqld/mysqld.sock;dbname=uguu (MySQL) or host=DBHOST;port=5432;dbname=uguu (Postgres)
  • DB_USER leave this as NULL if you are using SQLite.
  • DB_PASS leave this as NULL if you are using SQLite.
  • LOG_IP default is false seeing as Uguu is made to be privacy aware, if you want you can turn this on and the IP of the uploaded file will be stored in the database.
  • ANTI_DUPE default is false, if enabled a file already uploaded won't be uploaded again and instead the existing file url will be returned.
  • BLACKLIST_DB true/false depending if you want to activate file blacklist filtering.
  • FILTER_MODE if set to true the file MIME/extension filter will be in blacklist mode, if set to true it will be in whitelist mode.
  • RATE_LIMIT true/false for upload rate limit.
  • RATE_LIMIT_TIMEOUT in seconds for rate limit timeout, e.g 60.
  • RATE_LIMIT_FILES max files allowed to be uploaded within that rate limit timeout, e.g 100.
  • FILES_ROOT the location where uploaded files are to be stored, change this to /var/www/files/.
  • FILES_RETRIES maximum number of tries to regenerate filename in case an existing one already exists, this is highly unlikely and even if it does 15 tries is more than enough.
  • NAME_LENGTH the length of the new filename, default is 8, this can be increased or decreased however setting too low makes it easier to brute force a list of uploaded files or increases the chances of the filename already existing in the database.
  • ID_CHARSET the characters that will be used to randomly generate a new filename, just leave this as it is.
  • FILTER_EXTENSIONS is a list of the file extensions that will be included in the whitelist or blacklist filter, these can not be uploaded. It's recommended to keep the defaults since they are commonly used by malicious actors to spread malware via file sharing services. You may remove or add extensions to this list.
  • FILTER_MIME this is a list of MIME types that will be included in the whitelist or blacklist filter, a MIME identifies what kind of format a file is since you can save an executable file as a .jpg, it's recommended that blocked extensions match MIME types. You may remove or add MIME types to this list.

Compilation

Now we just need to compile the files using our configuration, the output will be in /var/www/uguu/dist/

Simply run:

cd /var/www/uguu/
bun install
make
make install

Setup file expiration

If you don't want files to expire and get deleted you can go ahead and skip this step.

In order for Uguu to delete files after they expire you will need to add a crontab entry on the root user, simply run crontab -e as root and add the following entry:

#Run file expiration check every 1 minute
* * * * * /usr/bin/php8.3 /var/www/uguu/dist/checkExpire.php

Finish

Uguu should now be up and running!

Optimization

In order for Uguu to perform better and have the ability to scale you should follow this Optimization Guide.

Add a custom footer
Add a custom sidebar

Clone this wiki locally