🌏 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/NriotHrreion/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

There is a plugin folder /src/plugins. Under the folder, there are plugins which are viewers for different kinds of file formats (e.g. *.mp4 *.avi).

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.

Firstly, you need to create a new tsx file. The name of the file had better end with ViewerPlugin.

And a metadata list of the plugin is needed.

{
    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: string) => <div>{dataUrl}</div> // The render of your viewer
        });
    }
}

This is an example plugin. Also be in (/src/plugins/registry/VideoViewerPlugin.tsx).

import { PluginMetadata } from "../../client/types";

export const VideoViewerPlugin: PluginMetadata = {
    name: "video-viewer",
    displayName: "视频查看器",
    setup({ addViewer }) {
        addViewer({
            id: "video-viewer",
            pageTitle: "Ferrum 视频查看器",
            route: "/video-viewer",
            formats: ["mp4", "avi"],
            render: (dataUrl: string) => <video src={dataUrl.replace("image", "video")} controls></video>
        });
    },
};

The components in the function render() will be rendered at the center of the whole page. And the param dataUrl is the data url (base64) of file that opened. You should pay attention to the mime type of the url: ("data:image/png;base64,.......")

export const ExamplePlugin: PluginMetadata<ViewerOption> = {
    // ...
    setup({ addViewer }) {
        addViewer({
            // ...
            render: (dataUrl: string) => {
                return (
                    // ...
                );
            }
        });
    }
};

Last, you should add your new viewer into the viewer list (/src/plugins/index.tsx).

PluginLoader.get().register(VideoViewerPlugin);
PluginLoader.get().register(MyViewerPlugin);
PluginLoader.get().register(OtherViewerPlugin);
// ... just add your plugin after it

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