How to build basic MVP with standalone Onlyoffice?

Hey, I’ve been struggling with this for a while already.

What I want to achieve is to create a React app (already in place) that will let me include a form via <DocumentEditor> from @onlyoffice/document-editor-react. This will only be used by me and never released to production so I don’t need any form of security, JWT, authentication and so forth. I just want to see how OnlyOffice performs with React and if it’s good for my use case. Will be used only on my localhost. Simple as that.

What I need here is basically the document server (if I understand it correctly).

So I spin up a Docker image:

 sudo docker run -e JWT_ENABLED=false -i -t -d -p 80:80 \
    -v ~/app/onlyoffice/files/logs:/var/log/onlyoffice  \
    -v ~/app/onlyoffice/files/data:/var/www/onlyoffice/Data  onlyoffice/documentserver

(HINT: can’t use /app/whatever as stated in docs because you can’t write to /app/ on MacOS, I strongly recommend changing this line in all of the docs to something else that’s writable in other OSes, this also will make all automatic sh installation scripts using /app/ fail on MacOS)

Now when I open localhost:80 I can see pretty OnlyOffice landing. But what would be the next step here? How do I create a new document or form and include it in my React app? Do I need to setup external db manually (aka “document storage service”)? Why can’t I just start editing documents right away? It’s confusing. Even if I click on integration link on your document server page: ONLYOFFICE Api Documentation - Basic concepts I can see an example that looks something like this:

config = {
    "document": {
        "fileType": "docx",
        "key": "Khirz6zTPdfd7",
        "title": "Example Document Title.docx",
        "url": "https://example.com/url-to-example-document.docx"
    },
    "documentType": "word",
    "editorConfig": {
        "callbackUrl": "https://example.com/url-to-callback.ashx"
    }
};

Where does this url-to-example-document.docx comes from along with its key? I can’t create in on my localhost:80 :o

The only other idea I had was to runsudo docker exec {containerId} sudo supervisorctl start ds:example then I can go to http://localhost/example/ but “Save” there is turned off and turning it on inside docker container @ /etc/onlyoffice/documentserver-example/local.json as follows:

{
  "services": {
    "CoAuthoring": {
      "autoAssembly": {
         "enable": true,
         "interval": "5m"
      }
    }
  }
  "server": {
    "token": {
      "enable": false,
      "secret": "Tt5D4mcdyNliXeiJFIDh",
      "authorizationHeader": "Authorization"
    }
  }
}

Does not help much, still can’t save :frowning: Example does not even seem to have any database settings in config so I guess it can’t be connected to my React app anyway? As it won’t save files anywhere even if somehow tricked to?

Thanks for any hints and explanations!

Hello @Mike1

Document Server is a tool that allows you to create/edit/save documents online.
First of all, please visit these pages to find out how Opening and Saving processes work in Document Server:
https://api.onlyoffice.com/editors/open
https://api.onlyoffice.com/editors/save
In general, you need to understand that Document Server works in conjunction with a document management system (where document manager and document storage service are the parts of it), so you cannot save the documents locally on your PC via Document Server.

To integrate Document Server with your DMS in your React project you need to install ONLYOFFICE Docs React component first. How to install and use it you can find here:
https://api.onlyoffice.com/editors/react

As a recommendation: Do not use localhost as Document Server address in initialization config, use IP instead.

Thank you Constantine, I have read all the docs but the issue I’m still having is quite trivial.

I have working Document Server and I understand I can’t create documents locally there.

But when I install ONLYOFFICE Docs React component ONLYOFFICE Api Documentation - ONLYOFFICE Docs React component or even try to integrate OnlyDocs in JS only as per docs: ONLYOFFICE Api Documentation - Basic concepts it always requires the “config”:

document": {
      "fileType": "docx",
      "key": "Khirz6zTPdfd7",
      "title": "Example Document Title.docx",
      "url": "https://example.com/url-to-example-document.docx"
    },

How can I feed React with document data if I can’t create the document in the first place? It’s a vicious circle where front-end layer requires document data before initialisation but I can only create the document using said front-end that won’t start because there aren’t any documents.

So to sum things up:

  • I have working Document Server,
  • I have working frontend client for the server, for the sake of simplicity let’s go with vanilla js, so I let’s assume I’m adding: <script type="text/javascript" src="http://127.0.0.1:80/web-apps/apps/api/documents/api.js"></script>,
  • but then I can’t do anything on the frontend because if I don’t provide “config” I end up with a broken OnlyOffice view
  • and when I try to add “config” as per docs I end up with the same view and it can’t work as I can’t provide any documents in config as they haven’t been created yet.

Thanks for any hints.

Hello again @Mike1

Front-end framework is used to initialize editors only. Document Server still needs to be integrated with a storage as I mentioned earlier.
Missing piece in this puzzle is that new files should be created from templates on the storage side and then passed to the Document Server for editing. As an independent integrator it is all up to you to implement the method for creation of new files on DMS side.

As a reference, you can download any simple test example in .zip archive from here, open or unzip an archive, locate /assets/new/ folder inside where you will find document templates that storage service is using to create new files and pass them to Document Server when user creates new document.

You can install any example of that list, integrate your Document Server with it to check out how it works.

Thank you @Constantine I’m afraid both documentation and docker image are a bit misleading here, for example after installing OnlyOffice Server and accessing localhost:80 it shows Integration options straight away first linking to js integration where it basically goes trough JS config and document storage service is mentioned there only once.

Are there some exemplary/simple storage options I could use? As I mentioned before I just want to give OnlyOffice a test run and I don’t want to write a lot of code based on somewhat lacking documentation. Even the saving website uses document data in config straight away whereas you can’t have any documents before saving (sorry for some reason the board disallows me to post links when I mention you) :frowning:

Hello @Mike1

The point is that Document server is just an editor in fact. It doesn’t contain/store any files or users data. As independent integrator, you have to integrate Document server to existing storage. We have storage examples that you can follow and research:
https://api.onlyoffice.com/editors/demopreview

If you can’t implement and support your own storage for some reason, you can use ready-to-go solutions:
https://www.onlyoffice.com/all-connectors.aspx

Thank you @Constantine I think I know where all the confusion comes from now.

I’ve tried using ready-to-go storage solutions and they simply don’t work for me.

I spin the default docker image of onlyoffice/documentserver, install strapi, add strapi plugin, connect it properly with the document server:

success

Then I can’t edit or add any new documents because, of course I can’t create new documents in Document Server per se (as you previously said) but somehow I can’t figure out how can I add new documents in Strapi (in this case)? I just need to have one document I can play with, and I’m struggling with it for roughly a week already :frowning:

Here’s the OnlyOffice Strapi view, I can’t post more than 1 media item per post so had to break it down.

Absolutely no idea how do I edit anything there if I can’t create any documents in the first place :smiley: Both Strapi plugin docs and your docs don’t state I need anything else in-between Strapi & the Document Server. So what am I missing? :frowning:

Ok, figured it out, I needed to add files to Media Library first. It still don’t work though, I can’t edit or preview any documents in ONLYOFFICE tab of strapi, getting {errorCode: -4, errorDescription: 'Download failed.'} all the time. Onlyoffice Server is properly connected and the documents are proper doc/docx files. How can I troubleshoot it if its all handled by Strapi?

nginx.error.log shows this, this is the default Docker installation + default Strapi, so seems like all the files should be there. I’ve seen this map error before, I’m not sure if it’s only a warning (map files shouldn’t be crucial for running the app, correct?) or truly fails file editing/opening:

2023/03/16 13:57:44 [error] 6316#6316: *23 open()
“/var/www/onlyoffice/documentserver/web-apps/vendor/socketio/socket.io.min.js.map” failed (2: No such file or directory), client: 172.17.0.1, server: , request: “GET /7.3.0-184/web-apps/vendor/socketio/socket.io.min.js.map HTTP/1.1”, host: “127.0.0.1”

[edit]

created empty map file in given path, fixed the issue!

Got a new one in /logs/documentserver/converter/out.log:

[2023-03-16T14:06:21.275] [ERROR] [localhost] [1_file_sample_100k_B_ad158053551678973585549] [1] nodeJS - error downloadFile:url=http://localhost:1337/onlyoffice/file?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjEiLCJpYXQiOjE2Nzg5NzU1NzcsImV4cCI6MTY3ODk3NTc1N30.2UBgughf3vaXzqdme30rgnvnoETfri3Li6Rz6VkXLII;attempt=3;code:ECONNREFUSED;connect:undefined Error: connect ECONNREFUSED 127.0.0.1:1337
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1159:16)

AFAIK the connection is not refused yet OnlyOffice thinks so. Will investigate but if you guys have any ideas feel free to share. The undefined is a bit worrying…

Hello @Mike1

Sorry for the late response.

Unfortunately, you are correct, Strapi is not capable of creating files from templates. By itself Strapi is a Content Management System (CMS) and differs from regular DMS in certain degree, including the ability to create files.
Even on Strapi plugin page from our official API it is stated:

This plugin enables users to edit office documents from Strapi using ONLYOFFICE Docs.

This error occurs when you are trying to use localhost as the address in Docker installation.
It doesn’t work because there is a separate localhost inside the Docker container, which means that Document Server is trying to find the resource inside the container and fails.
Please try accessing your Strapi app via external/internal IP of your machine. To make sure I’d recommend external/internal IP for Document Server too.

Note that localhost and 127.0.0.1 are functionally identical.

Thank you @Mike1, I have actually used the proper IP somehow Docker image kept on using localhost. Recreating the container helped.

I think I have the last question - If I have OnlyOffice server running and files saved is there a way to include my files handled by Strapi on external (JS/React) pages eg. like at ONLYOFFICE Api Documentation - Basic concepts ? That is my end goal basically.

Hello @Mike1

Glad to hear that the issue with localhost is resolved now.

In theory, you can use Strapi. To properly render editors in your project please refer to React component usage article from our API:
https://api.onlyoffice.com/editors/react#use

Note that you have to pass "url" field as a direct link to the file so Document Server can download it in order to open for editing.

Additional note: we have recently updated React component to version 1.3.0:
https://www.npmjs.com/package/@onlyoffice/document-editor-react

@Constantine thank you, everything seems to work, almost. There’s the single issue I was most afraid of:

<DocumentEditor
  id="docxEditor"
  documentServerUrl="http://documentserver/"
  config={{
    "document": {
      "fileType": "docx",
      "key": "Khirz6zTPdfd7",
      "title": "Example Document Title.docx",
      "url": "https://example.com/url-to-example-document.docx"
    },
  }}
  events_onDocumentReady={onDocumentReady}
/>

I’ve got the proper values for all the fields now (including file url) but where do I get the “key” value from? When I try to omit it I get the infamous The document security token is not correctly formed error. As I recall every single file has different key value? Placing JWT token from

sudo docker exec {containerId} /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

renders the same error.

Any ideas how do I handle this without recreating my whole setup & disabling JWT? At this point I have no idea where to get the “key” from. Thanks!

Hello @Mike1

Please do not mix up notions document key and JWT Token.
On one hand, the document key is the unique identifier of the document used by Document Server to recognize the documents. More about it here:
https://api.onlyoffice.com/editors/config/document#key
For example, you can check out these articles to find out how document key is used:
https://api.onlyoffice.com/editors/open
https://api.onlyoffice.com/editors/coedit

On the other hand, JWT Token is used to encrypt requests from client to server to increase security measures.
Basic explanation of JWT Token encryption you can find here:
https://jwt.io/introduction
In this article from our official API you can find out how the process of token validation is set up on Document Server side:
https://api.onlyoffice.com/editors/signature/
A bit down below in this article you can find samples of token generation:
https://api.onlyoffice.com/editors/signature/#code-samples

Note that as an independent integrator it is all up to you to develop and implement JWT Token generation and validation and document key generation on your app side.

With that said, the issue The document security token is not correctly formed is related to the usage of JWT Token on Document Server side and absence of it on your app side. Possible ways to solve it are:

  1. Implement JWT Token authorization on your app side;
  2. Disable JWT Token on Document Server side.

Thank you, that’s what I thought. Everything’s clear now!

As a feedback: I think there’s a problem with how you handle JWT Token, particularly communication about it.

JWT Token is enabled by default for OnlyOffice Document Server therefore it should be clearly stated in all the docs related to integration (eg. with React) & preferably included in the react lib as well. Seems like “token” in “config” does what I have in mind but in my case it does not work as expected still returning the not correctly formed token error even though the JWT token is valid. Shouldn’t this work:

<DocumentEditor
  id="docxEditor"
  documentServerUrl="http://documentserver/"
  token="JWTTOKENSTRING"
  config={{
    "document": {
      "fileType": "docx",
      "key": "Khirz6zTPdfd7",
      "title": "Example Document Title.docx",
      "url": "https://example.com/url-to-example-document.docx"
    },
  }}
  events_onDocumentReady={onDocumentReady}
/>

?

The example should always include “token” as it’s maybe opt-in but enabled by default.

Also there’s some inconsistency because I’ve tried a few different integrations and they won’t simply work with JWT Token disabled, for example Strapi needs JWT Token in order to connect with the Document Server and it’s a required field so can’t be left empty or omitted. Therefore turning JWT Token off renders many (all?) existing integrations useless.

Hello @Mike1

I’m very sorry for the late reply.

Thanks for the feedback.

It won’t work by simply inserting secret key as a string. Please refer to above mentioned page with basic explanation of JWT token first to find out more about token structure, then check out this page in our API to see an example of the way how it should be passed from your React project to Document Server:
https://api.onlyoffice.com/editors/signature/browser
The JWT token payload should correspond to the config structure of the initialization request as per guide for React component.

To build a basic MVP with standalone OnlyOffice and integrate it into your React app, follow these steps:

Start by running the OnlyOffice Document Server Docker image. The command you provided is correct:
sudo docker run -e JWT_ENABLED=false -i -t -d -p 80:80
-v ~/app/onlyoffice/files/logs:/var/log/onlyoffice
-v ~/app/onlyoffice/files/data:/var/www/onlyoffice/Data onlyoffice/documentserver
This command starts the document server on localhost:80.

After starting the document server, you can access the OnlyOffice landing page by opening http:// localhost:80 in your browser.

To create a new document or form and include it in your React app, you need to use the OnlyOffice Document Editor API. The example configuration you mentioned demonstrates how to integrate the API. The url-to-example-document.docx is just an example URL to a document file. You can replace it with the URL of your own document file. The key represents a unique identifier for the document.

To enable saving the edited documents, you need to configure the document server. Inside the Docker container, locate the /etc/onlyoffice/documentserver-example/local.json file. Modify it as follows:
{
“services”: {
“CoAuthoring”: {
“autoAssembly”: {
“enable”: true,
“interval”: “5m”
}
}
},
“server”: {
“token”: {
“enable”: false,
“secret”: “Tt5D4mcdyNliXeiJFIDh”,
“authorizationHeader”: “Authorization”
}
}
}

Save the changes to the local.json file and restart the document server container.

After restarting, you can access the example page by running the following command inside the Docker container:
sudo docker exec {containerId} sudo supervisorctl start ds:example

Visit http://localhost/example/ in your browser to see the example page. You should now be able to edit and save documents.

Regarding the requirement for a database connection, OnlyOffice Document Server does not directly manage document storage. It is primarily designed to work with third-party storage solutions or document management systems. If you want to save the edited documents, you’ll need to configure a document storage service or integrate with an existing one.

For more detailed information and guidance, I recommend referring to this blog post: How to Create MVP.

I hope this helps! Let me know if you have any further questions.