freenom

Announcement

Why This Exists

What Notifications Look Like

Before You Start

Configure Notifications (Email / Telegram Bot / WeCom / ServerChan / Bark / Pushplus)

⛵ Docker Compose Deployment

Docker Deployment (recommended, and usually the simplest option)

Heroku Deployment

Railway Deployment

Koyeb Deployment (a good fit if you do not have your own server)

Mogenius Deployment (no longer viable)

☁ Cloud Function Deployment (no longer actively supported)

Deploy from Source

Donation List

❤ Support the Project

A Personal Note

Author

All Contributors

TODO List

Other Language Ports

Acknowledgements

License

Announcement

• Community members created a Telegram group called Freenom Renewal Bureau for discussion, testing, and feedback. You can join directly here: https://t.me/freenom_auto_renew

Why This Exists

Freenom is the only provider I know of that offers free top-level domains, but those domains have to be renewed every year, and only one year at a time. I had a pile of domains registered at different times, and renewing them manually got old fast, so I wrote this script to automate the whole thing.

What Notifications Look Like

The script sends a notification whether renewal succeeds, fails, or crashes. Renewal-related notifications also include details like how many days remain before an unrenewed domain expires. The screenshot below shows the email version of that message.

Before You Start

• A VPS or server. Any box will do, although Debian is the easiest path. If you deploy without Docker, you need PHP 8.1 or newer. If you do not have a server, the hosted options later in this README may be a better fit.
• A sender mailbox, if you want email notifications. The script knows how to auto-configure Gmail, QQ Mail, 163 Mail, and Outlook. If you want to use another provider or your own mail server, check the email-related comments in .env.example.
• A recipient mailbox, if you want to receive email notifications.
• Both mailbox fields are optional because the project also supports Telegram Bot, WeCom, ServerChan, Bark, and Pushplus. You only need MAIL_USERNAME, MAIL_PASSWORD, and TO if you choose email notifications.
• A little patience.

Configure Notifications

This project supports Email, Telegram Bot, WeCom, ServerChan, Bark, and Pushplus. Pick one and configure only that path. If you are on iOS, Bark is usually the cleanest option. For most other users, use whichever channel you are already comfortable with. I generally do not recommend ServerChan: the daily message cap is restrictive, and some content is hidden behind its paid tier. The same basic setup effort usually goes further with WeCom, and those notifications show up directly in the standard WeChat client.

Jump straight to a section:

Email Notifications

Telegram Bot

WeCom

ServerChan

Bark

Pushplus

Email Notifications

This section covers Gmail, QQ Mail, and 163 Mail. Only read the provider you actually use. QQ Mail and 163 Mail both use your mailbox plus an authorization code. Gmail now effectively means your mailbox plus an app password.

(Click to expand or collapse each provider.)

Gmail

If you use multiple Gmail accounts, open the settings page in a private or incognito window first. That makes it much easier to land on the right account.

1. In Settings > Forwarding and POP/IMAP, enable:

• Enable POP for all mail
• Enable IMAP

Then save the change.

1. Turn on 2-Step Verification.

Official guide: Turn on 2-Step Verification

1. Create an app password for this script.

Official guide: Sign in with App Passwords

Gmail no longer supports "less secure app" logins. Use your account plus an app password.

---

QQ Mail

In Settings > Accounts > POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV Service, enable POP3/SMTP Service.

QQ Mail will ask you to send an SMS to Tencent. After that, it will display an authorization code. Use your mailbox account plus that authorization code to sign in, and keep the code for your .env configuration.

---

163 Mail

In Settings > POP3/SMTP/IMAP, enable both POP3/SMTP Service and IMAP/SMTP Service, then save the change.

Next, open the Client Authorization Password section and generate an authorization code. The UI may look different from the screenshot in the Chinese README depending on whether you have already created one. Like QQ Mail, 163 Mail may also require an SMS step before it will issue the code.

If the recipient does not see messages from a 163 mailbox, check the spam folder first.

---

After that, set MAIL_USERNAME and MAIL_PASSWORD to your mailbox and password or token, set TO to the mailbox that should receive notifications, and set MAIL_ENABLE=1 in .env.

If you do not want email notifications at all, set MAIL_ENABLE=0 in the root .env file.

That is it for email notifications.

Telegram Bot

For the full Telegram Bot setup flow, see the wiki: Telegram Bot

WeCom

For the full WeCom setup flow, see the wiki: WeCom

ServerChan

For the full ServerChan setup flow, see the wiki: ServerChan

Bark

For the full Bark setup flow, see the wiki: Bark

Pushplus

Pushplus is also supported. Set PUSHPLUS_KEY to your token in .env, then set PUSHPLUS_ENABLE=1 to turn it on. If Pushplus is the only channel you want to use, leave the other notification methods disabled.

---

That covers notifications. Next up are the supported deployment options. Docker is still the path I recommend for most people because it removes nearly all environment drift.

---

⛵ Docker Compose Deployment

Note: this path is currently marked beta and only supports amd64. If you are on arm or another architecture, wait for a later update. If you need a server, one option is cheap US VPS.

1. Install Docker and Docker Compose

Debian / Ubuntu (recommended)

apt-get update -y;
apt-get install -y wget vim git make;
wget -qO- get.docker.com | bash;
systemctl start docker;
sudo systemctl enable docker.service;
sudo systemctl enable containerd.service;
docker version;
DOCKER_COMPOSE_VER=2.24.3;
DOCKER_CONFIG=/usr/local/lib/docker;
mkdir -p $DOCKER_CONFIG/cli-plugins;
curl -SL https://github.com/docker/compose/releases/download/v${DOCKER_COMPOSE_VER}/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose;
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose;
docker compose version;

CentOS

yum update -y;
yum install -y wget vim make;
wget -qO- get.docker.com | bash;
systemctl start docker;
sudo systemctl enable docker.service;
sudo systemctl enable containerd.service;
docker version;
DOCKER_COMPOSE_VER=2.24.3;
DOCKER_CONFIG=/usr/local/lib/docker;
mkdir -p $DOCKER_CONFIG/cli-plugins;
curl -SL https://github.com/docker/compose/releases/download/v${DOCKER_COMPOSE_VER}/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose;
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose;
docker compose version;

2. Clone the Repository

git clone https://github.com/luolongfei/freenom.git && cd freenom

3. Configure the Project

3.1 Get a Wit.ai Token

1. Open https://wit.ai.
2. Sign in with Facebook or create an account with email only.
3. Go to https://wit.ai/apps and create a new app.
4. Choose English as the language, pick any name you want, set the app to Private, and create it.
5. Open Management > Settings (https://wit.ai/apps/<App ID>/settings).
6. Copy the Client Access Token and put it in .env as WIT_AI_KEY='your Client Access Token'.

3.2 Edit .env

Replace the sample values in .env with your own configuration. If you are upgrading from an older release, you can also copy your previous .env into the new project root and let the script update it for you. Field-by-field explanations live in .env.example.

cp .env.example .env;
vim .env;

When you are done, save and quit.

4. Start the Stack

Run these commands from the directory that contains docker-compose.yml.

make up

That is the whole startup flow. Use make logs if you want to tail the live logs.

4.1 Common Commands

Start the stack or update to the latest version

make up

Stop the stack

make down

View live logs

make logs

Clean up disk space used by containers

make clear

Restart the containers

make restart

That is the end of the Docker Compose section.

Docker Deployment

If you have your own server, this is the deployment mode I recommend most.

Docker Hub: https://hub.docker.com/r/luolongfei/freenom

The image supports linux/amd64, linux/arm64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, and linux/arm/v6, so it should work on most VPS platforms as well as NAS devices and Raspberry Pi-class hardware.

1. Install Docker

1.1 Log in as root and run the one-line installer

Update packages and install the basic tools first. Pick the command that matches your OS.

Debian / Ubuntu

apt-get update && apt-get install -y wget vim make

CentOS

yum update && yum install -y wget vim make

Then install Docker:

wget -qO- get.docker.com | bash

Notes:

• Use a KVM-based VPS. OpenVZ does not support Docker installation.
• CentOS 8 is not supported by this installer script.
• For anything more advanced, use the official Docker installation guide.

1.2 Start and enable Docker

Start the Docker service

systemctl start docker

Check Docker status

systemctl status docker

Enable Docker at boot

systemctl enable docker

2. Run the Container

2.1 Create and start the container

Basic command:

docker run -d --name freenom --restart always -v $(pwd):/conf -v $(pwd)/logs:/app/logs luolongfei/freenom

If you only want to run the renewal script once and use the cookies.txt session from the current directory, paste your browser-exported cookies JSON into cookies.txt, then run:

docker run --rm -v $(pwd):/conf -v $(pwd)/logs:/app/logs luolongfei/freenom run-once

The container automatically reads /conf/cookies.txt. If cookies.txt is empty, cookie-session mode is not enabled and the script falls back to the original .env account/password configuration.

If you want to set a custom run time: