What are the requirements for mg-substack?

Integrations & API
1

Greetings!
I am reasonably technical, but am new to the Ghost ecosystem.

I am currently an (unhappy) substack user. I found the mg-substack package, and thought: This might be my ticket off substack! (because I need to export a lot of images and mp4 content, which this tool appears to do)

The QUESTION:
Referring to: https://github.com/TryGhost/migrate/tree/main/packages/mg-substack
Starting from a vanilla Win or Linux environment, what are the pre-reqs to run mg-substack?

It seems to assume something (a running ghost server?), but I do not see a ā€œsetup from scratchā€ document/steps.

If someone could please point me to the relevant doc or fill me in, would be much appreciated!

2

Youā€™ll need to install node.js which includes npm, then follow the readme instructions further down. You can install the LTS version of node if it asks you to pick a version :slight_smile:

3

Thanks!
commands like: npm install
are done within node? (I think they are linux cmd line, right?)

4

Youā€™ll also need your distroā€™s build tools for some of the migration package. (Build-essential on Ubuntu.)

5

If you want to go the technical route of using a CLI tool, you obviously can cos we made that - but we have focused all of our efforts on making things easy to use on the UI:

CleanShot 2025-04-02 at 13.42.48@2x
CleanShot 2025-04-02 at 13.42.48@2x2170Ɨ930 121 KB

If you login to a running Ghost instance, and navigate to settings > import/export (Or search for something like migrate) youā€™ll get a nice UI that will help you through the process :)

Documentation is here: How do I import my data from Substack?

2 Likes
6

I get an error running ā€œmigrate substackā€ā€¦ How to recover? [OPEN ISSUE]

###@###:/usr/share$ sudo migrate substack --pathToZip /usr/2025dump.zip --url https://###.substack.com -V --scrape all --sizelimit 500
[sudo] password for ###:
info Migrating from export at /usr/2025dump.zip
[STARTED] Initializing
[OUTPUT] Workspace initialized at /tmp/mg/f26e7d3c65f16f91a87837ed58562005-substack-2025dump
[COMPLETED] Initializing
[STARTED] Read csv file
[2025-04-02 14:09:26] ERROR
[FAILED] Unable to read zip file /usr/2025dump.zip: Error: ADM-ZIP: Invalid filename
[2025-04-02 14:09:26] INFO
info Cached files can be found at /tmp/mg/f26e7d3c65f16f91a87837ed58562005-substack-2025dump
Error: ENOENT: no such file or directory, open ā€˜/usr/share/localhost_development.logā€™
at readFileSync (node:fs:449:20)
at showLogs (file:///usr/lib/node_modules/@tryghost/migrate/lib/utilties/cli-log-display.js:8:21)
at TypeCommand.run [as _runHandler] (file:///usr/lib/node_modules/@tryghost/migrate/commands/substack.js:260:5)
at async Promise.all (index 23)
###@###:/usr/share$

7

@raf-zim Iā€™ve moved your new question into this thread, as itā€™s all the same topic :slight_smile:

8

@Hannah Thanks!

I do need the CLI tool to work, because that would be my ā€œpoint in timeā€ backup as part of migrating from substack.

(I am not aware of any other way to do an export from substack that includes assets)

With the topics merged, how do we engage the issue I am hitting?

9

@Cathy_Sarisky Yes, the build tools are required, but the README does not mention themā€¦ (and they are not needed to install and run ghost itself).

I suggest that the readme be expanded to note thisā€¦ (or that the mg-substack installer include the build tools as a dependency so it is auto-magic?)

1 Like
10

File a PR to fix the readme? :)

11

File a PR to fix the readme?

Will do!

12

@Hannah

I am going to break the command line issue into its own topic (will repost, I guess), as there are a range of related topics to dig into and this thread is all over the place maybe?

If my new thread is a sin of some kind, you can delete it?

13

@Hannah Thank you!

Using the UI is not feasible (I tried!) because:

  1. My test/development environments are not internet visible [this is not going to change]. When I try to do the substack import within ghost, it fails saying my instance must be internet visible. (this will never be possible for me during dev/test/evaluation)
  2. I will be doing this migration many times as part of the dev/eval process. The substack is updated 1-2 times a week. I need the command line.
  3. I also need control over parameters. For example, there are large mp4 files on substack (50GB, 100GB, poss larger, havenā€™t inventoried yet)

Soooooo, I need the cmd line to workā€¦

14

Sounds like weā€™d better figure out how to get this working, then! The error appears to be coming from adm-zip, which parses zip files. Good places to start (with apologies if youā€™ve already tried some/all of these):

Does the file exist at /usr/2025dump.zip ?
Is the file definitely a zip, and not a .gz or .tgz?
If you unzip it and take a look inside, any surprises?

The later ENOENT error is that the tool is expecting /usr/share/localhost_development.log to exist. Iā€™m thinking thatā€™s a distractor, but a quick touch /usr/share/localhost_development.log before running is likely to resolve that error, making it a little clearer that it isnā€™t the problem ā€“ and you might get something useful in that log.

15

@Cathy_Sarisky

Thank you so much for engaging!

I figured it outā€¦

C.f. Mg-substack -- what it does and doesn't do... :-(

1 Like
16

I am reviewing the relevant Ghost docs, and realize I ā€œread inā€ things thatā€¦ arenā€™t thereā€¦

Background: I have a lot of media assets (images and mp4 files) hosted within substack. These assets are not included in a substack export created within the substack console. (This is one of the reasons I dislike substackā€¦ it doesnā€™t give me a dump of all my data.)

Goal: A major goal in migrating to ghost is to migrate my entire content base out of the substack-verse into a -verse that I own/manage/back-up.

Question: Where in the migration-to-ghost are these assets migrated?

I mistakenly thought that ā€œmigrate substackā€ utility did this. In other words, I thought ā€œmigrate substackā€ was going to walk my substack and create a magical zip of everything (including assets) that would be in a format ready to import to ghost.

I now see (after 1-2 hours of misdirected hacking) that this is not the case. I now understand that ā€œmigrate substackā€ does not touch assets. I now understand that ā€œmigrate substackā€ simply massages the existing ā€œsubstack exportā€ for migration to ghost.

  1. This makes me sad. (I thought ghost was my arrival!)
  2. Is there a way to achieve what I seek?

E.g. If 2 years of assets will remain in the substack-verseā€¦ the calculus [to justify migration] is not what I would like it to beā€¦