@nocp/ferrum

Ferrum Explorer

Explore throughout your server

English | 中文

Description

Ferrum Explorer is a web-based file explorer app for servers.

Because it's only maintained by me, so it has many problems and bugs. You can create a issue or pull request to tell me or fix it.

Why its name is Ferrum?

File Explorer -> FE -> Fe (Chemical Element) -> Ferrum

Can I have a look of it?

Demo: https://ferrum-demo.nin.red (The password is 123456)

Deploy & Use

First, you need to make sure that your server (or computer) has installed Nodejs.

1. Download and install

git clone https://github.com/nocpiun/ferrum.git
cd ferrum
npm i

2. Run the app

npm run start

If you're using Linux, you need to add sudo before the command.

3. Enter http://localhost:3300, the default password is 123456.

To get update

Do the following commands, then do npm run start.

git fetch origin main:temp
git merge temp
npm i

If error at npm i, just try:

npm i --legacy-peer-deps
# or
npm i --force

Something to notice

Ferrum Explorer requires ports 3300 3301 to launch. If you see it reports address already in use :::xxxx, you should have a check to whether you've launched Ferrum Explorer and whether other apps are using the ports. And see the following steps.

Windows

netstat -aon | findstr [[here write the port it reported]]
taskkill /f /pid [[here write the PID the above command returned]]

Linux & Mac OS

lsof -i:[[here write the port it reported]]
kill -9 [[here write the PID the above command returned]]

If it reports ENOSPC: System limit for number of file watchers reached, watch 'xxx' and you're using Linux, please do:

sudo sysctl fs.inotify.max_user_watches=582222 && sudo sysctl -p

Plugin

Write a Viewer Plugin

Viewer is a page that is shown when the user opens a file. The viewer's page will be shown when the user opens the file format(s) the viewer's option has specified. For example, a video viewer, its page will be shown when the user open a .mp4 file.

You need to create a new jsx file. And a metadata list of the plugin is needed. (The following is a complete example).

({
    name: "example-viewer",
    displayName: "Example Viewer",
    setup({ addViewer }) {
        addViewer({
            id: "example-viewer", // The ID of your viewer
            pageTitle: "Example Viewer", // This will be shown on the top of your viewer's page
            route: "/example-viewer", // The route of your viewer's page
            formats: [], // The formats that your viewer supports
            render: (dataUrl) => <div>{dataUrl}</div> // The render of your viewer (`dataUrl` is a base64 data url)
        });
    }
})

Then, add your plugin in settings.

Plugin I18n

If you want to make your plugin supports different languages, just create a variable that stores your texts:

const i18n = {
    "zh-CN": {
        "plugin.hello": "你好"
    },
    "en": {
        "plugin.hello": "Hello"
    }
};

Then, put this variable into your plugin metadata list:

({
    // ...
    setup(apis) {
        // ...
    },
    i18n, // <== Here
    // ...
})

If you would like to use one of the texts in the i18n list, you just need to write down the key of the text and add a $ before it. For example: $plugin.hello.

({
    // ...
    setup({ addViewer }) {
        addViewer({
            // ...
            pageTitle: "$plugin.hello", // <== Just like that
            // ...
        });
    },
    i18n,
    // ...
})

Testing

Ferrum Explorer is using Jest to test code.

npm run test

Contributing

Contributions to Ferrum Explorer are welcomed. You can fork this project and start your contributing. If you don't know how to do, please follow the instruction Creating a Pull Request from a Fork.

I'll check the Pull Request list in my spare time. I can't make sure that every Pull Request will be seen by me at once.

Scripts

An explanation of the package.json scripts.

• start Launch the app in production mode
• dev Launch the app in development mode
• server Only launch the server
• client Only launch the client
• build Create a production build (No using singly)
• build:netlify Create a production build (For the deployment of Netlify)
• test Run tests

Note

Fun Fact: This project learnt a lot from Takenote. Takenote is also awesome.

LICENSE

MIT